Errors and Debugging

Diagnose validation, authentication, credit, and upstream issues.

Error Codes

Name	Type	Description
400	Bad Request	Invalid schema or parameters.
401	Unauthorized	Missing/invalid API key.
402	Payment Required	Insufficient credits.
404	Not Found	Unknown route or resource.
429	Too Many Requests	Rate limited.
500	Internal Server Error	Gateway internal failure.
502	Bad Gateway	Upstream/provider failure.
503	Service Unavailable	Temporary service outage.

Standard Error Shape

json

{
  "error": {
    "message": "Rate limit exceeded",
    "type": "rate_limit_error",
    "code": 429,
    "param": null
  }
}

402 Extended Error Shape

json

{
  "error": {
    "type": "insufficient_credits",
    "message": "Insufficient credit balance",
    "code": "insufficient_credits",
    "balance": {
      "current": 2.5,
      "threshold": 5,
      "currency": "credits"
    },
    "actions": {
      "top_up_url": "/v1/customer/credits/packages",
      "support_url": "/support"
    }
            }
}

This 402 payload is an extension that adds error.balance and error.actions. The extension may use a semantic code value ("insufficient_credits") while standard errors use the canonical {message, type, code, param} shape.

Debugging Headers

Name	Type	Required	Description
x-request-id	response header		Canonical request identifier for support/debugging.
Retry-After	response header		Seconds to wait before retrying a 429 response.

502 Type

502 responses use api_error in the error type field.