Documentation

Errors

Error response format and every status code the API can return.

Error format

Errors return a non-2xx HTTP status and a JSON body with an error object containing a machine-readable code and a human-readable message. Some errors include extra fields (for example, recharge_url or retry_after_seconds).

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Wallet balance is zero. Please recharge.",
    "recharge_url": "https://nabh.cloud/wallet"
  }
}

Status codes

HTTP	Code	Meaning
400	`INVALID_REQUEST`	Malformed JSON, or a required field such as model is missing.
401	`AUTHENTICATION_ERROR`	API key is missing, invalid, expired, or revoked.
402	`INSUFFICIENT_BALANCE`	Wallet balance is zero. Includes a recharge_url.
403	`PERMISSION_DENIED`	The requested model is not available on your plan.
403	`IP_NOT_ALLOWED`	Request IP is not in the key's whitelist.
404	`INVALID_REQUEST`	Unknown model ID.
429	`RATE_LIMIT_EXCEEDED`	Too many requests. Includes Retry-After and X-RateLimit-Reset headers.
500	`API_ERROR`	Unexpected internal or upstream provider error.
504	`GATEWAY_TIMEOUT`	The upstream model did not respond within 60 seconds.

Handling errors

Check the HTTP status first, then branch on error.code for specific handling.
On 402 INSUFFICIENT_BALANCE, prompt the user to recharge using the provided recharge_url.
On 429 RATE_LIMIT_EXCEEDED, wait for Retry-After then retry with backoff — see Rate Limits.
On 504 GATEWAY_TIMEOUT, retry idempotently; very long generations may need a smaller request.