// RFC 7807 Problem Details for HTTP APIs
{
  "type": "https://api.helloaihub.com/errors/insufficient-account-balance",
  "title": "Insufficient Account Balance",
  "status": 422,
  "detail": "Your wallet balance of $42.50 is insufficient for transaction amount $100.00.",
  "instance": "/api/v1/wallets/w_98214/charges/tx_001",
  "invalid_params": [
    {
      "name": "amount",
      "reason": "Exceeds available balance"
    }
  ]
}

// High-Throughput Cursor Pagination Response Envelope
{
  "data": [
    { "id": "evt_104", "type": "AUTH_SUCCESS", "timestamp": "2026-08-16T04:30:00Z" }
  ],
  "pagination": {
    "limit": 20,
    "has_more": true,
    "next_cursor": "eyJpZCI6ImV2dF8xMDQiLCJ0cyI6MTcyMzgxNjIwMH0=",
    "prev_cursor": null
  },
  "_links": {
    "next": "/api/v1/events?limit=20&cursor=eyJpZCI6ImV2dF8xMDQiLCJ0cyI6MTcyMzgxNjIwMH0="
  }
}

-- Atomic Token-Bucket Rate Limiter in Redis Lua
local key = KEYS[1]
local max_capacity = tonumber(ARGV[1])
local refill_rate = tonumber(ARGV[2]) -- tokens per second
local current_time = tonumber(ARGV[3])
local requested_tokens = tonumber(ARGV[4])

local state = redis.call('HMGET', key, 'tokens', 'last_updated')
local tokens = tonumber(state[1]) or max_capacity
local last_updated = tonumber(state[2]) or current_time

-- Refill tokens based on elapsed time
local elapsed = math.max(0, current_time - last_updated)
tokens = math.min(max_capacity, tokens + elapsed * refill_rate)

if tokens >= requested_tokens then
    tokens = tokens - requested_tokens
    redis.call('HMSET', key, 'tokens', tokens, 'last_updated', current_time)
    redis.call('EXPIRE', key, math.ceil(max_capacity / refill_rate))
    return {1, math.floor(tokens)} -- Allowed!
else
    return {0, math.floor(tokens)} -- 429 Too Many Requests!
end