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 or input is missing.
401	`AUTHENTICATION_ERROR`	API key is missing, invalid, or expired.
402	`INSUFFICIENT_BALANCE`	Wallet balance (or institution pool) is exhausted. Includes a recharge_url when it's your own wallet.
403	`PERMISSION_DENIED`	The requested model isn't available on your plan, or the key isn't scoped correctly for an institution course.
403	`IP_NOT_ALLOWED`	Request IP is not in the key's whitelist.
403	`ACCOUNT_SUSPENDED`	The account has been suspended.
404	`INVALID_REQUEST`	Unknown model ID, or the model was called on the wrong endpoint — check that model's docs page for its exact base URL.
411	`MISSING_CONTENT_LENGTH`	Audio upload is missing a Content-Length header.
413	`INPUT_TOO_LARGE`	Text-to-speech input exceeds the 8,000-character limit.
413	`FILE_TOO_LARGE`	Audio upload exceeds the 25 MB limit.
429	`RATE_LIMIT_EXCEEDED`	Too many requests. Includes Retry-After header and retry_after_seconds in the body.
503	`SERVICE_UNAVAILABLE`	A dependency (auth, rate limiter, model catalog, course policy) is temporarily down. Safe to retry.
504	`GATEWAY_TIMEOUT`	The model provider did not respond within 60 seconds. Safe to retry.
5xx	`API_ERROR`	The model provider returned an unexpected error or the upstream connection failed. Safe to retry.

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 503 SERVICE_UNAVAILABLE, retry with backoff — it means a dependency is temporarily down, not that your request was invalid.
On 504 GATEWAY_TIMEOUT or API_ERROR, retry with backoff — these mean the model provider timed out or errored, not that your request was invalid.