Skip to main content

​
Errors

All error responses share a common shape. Use error.code for programmatic handling and error.message for logging.

​
Response format

{
  "success": false,
  "data": null,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient balance. Current balance: 50.00; required: 100.00",
    "details": {
      "current_balance": 50.00,
      "required_amount": 100.00
    }
  },
  "meta": {
    "request_id": "req_xxxx"
  }
}

​
Error codes

CodeHTTPDescriptionAction
AUTH_INVALID_KEY401Invalid API KeyCheck key
AUTH_EXPIRED_TOKEN401JWT expiredRefresh token
AUTH_INSUFFICIENT_PERMISSION403Permission deniedCheck scope
RATE_LIMIT_EXCEEDED429Too many requestsBack off; use Retry-After
ACCOUNT_DISABLED403Account disabledContact support
INSUFFICIENT_BALANCE402Balance too lowRecharge
SESSION_NOT_FOUND404Session missingCheck session_id
SESSION_EXPIRED410Session expiredCreate new session
SESSION_LIMIT_REACHED429Session limitTerminate old sessions
PRODUCT_NOT_FOUND404Product invalidList products
PRODUCT_OUT_OF_STOCK409Out of stockRetry or other product
INVALID_REQUEST400Bad parametersFix request body
IDEMPOTENCY_CONFLICT409Duplicate idempotency keyUse new key or reuse cached response
BACKEND_ERROR502Backend failureRetry with backoff
BACKEND_TIMEOUT504Backend timeoutRetry
INTERNAL_ERROR500Internal errorContact support

​
Rate limit headers

All responses include:
HeaderDescription
X-RateLimit-LimitMax requests per window
X-RateLimit-RemainingRemaining in window
X-RateLimit-ResetWindow reset (Unix timestamp)
On 429, Retry-After (seconds) is also present. Use it before retrying.

​
Retry guidance

  • Do not retry: AUTH_INVALID_KEY, INSUFFICIENT_BALANCE, INVALID_REQUEST, SESSION_NOT_FOUND — fix input or state.
  • Refresh and retry: AUTH_EXPIRED_TOKEN — get new token then retry.
  • Wait and retry: RATE_LIMIT_EXCEEDED — sleep Retry-After then retry.
  • Exponential backoff: BACKEND_ERROR, BACKEND_TIMEOUT — retry with 2^attempt delay.
Next: Best practices (idempotency, telemetry, rotation).