Skip to main content

​
Errors

​
Validation and content errors returned

The Nunchux API uses standard HTTP status codes. All error responses include a JSON body describing what went wrong.

​
Client Error Response Format

Client errors (4xx) return a JSON body. Auth, rate-limit, and billing errors carry an error object; request-validation failures carry a plain detail string.

​
Client Error Codes

​
400 Bad Request

The request is missing required parameters or contains invalid values such as missing prompt, invalid model ID, invalid dimensions. Returned as a plain detail string.
Retry Guide — Do not retry. Fix the request parameters before resending.

​
401 Unauthorized

The API key in the X-API-Key header is missing, malformed, unknown, revoked, or expired (codes: missing_api_key, invalid_key_format, invalid_api_key, key_revoked, key_expired).
Retry Guide — Do not retry. Check that your API key is correct and active.

​
403 Forbidden

The account does not have access to the requested model. Restricted models need an explicit grant. This response carries detail, not the error envelope.
Retry Guide — Do not retry. Use a public model, or contact support to request access.

​
429 Rate Limit

Too many requests in a short period. Code rpm_limit_exceeded for the per-minute cap, concurrent_limit_exceeded for the simultaneous-job cap. Back off and retry.
Retry Guide — Implement exponential backoff. Start with a 1-second delay, then double on each retry (1s → 2s → 4s → 8s). Cap at 3–5 retries.

​
402 Insufficient Credits

Your account does not have enough credits for this request. The response includes your current balance and the cost so you know exactly how many credits to add.
Credit metadataThe 402 body is the standard error object. code, message and request_id are always present. The credit amounts are not always included. When they are, they ride in error.details, with the deprecated creditsRequired and creditsBalance mirrors alongside.
Retry — Do not retry. Check your credit balance and purchase more credits if needed. See Credits & Pricing.

​
Server Error Response Format

Server errors (5xx) return a JSON body with a detail string. When the inference backend supplies a typed envelope, an error object with a machine-readable code rides alongside it.

​
Server Error Codes

​
500 Internal Server Error

An unexpected error occurred on the server.
Retry Guide — Safe to retry with exponential backoff. Credits are automatically refunded on failure.

​
502 Bad Gateway

The inference service returned no data. The request was processed but no output was generated.
Retry Guide — Safe to retry with exponential backoff. Credits are automatically refunded on failure.

​
503 Service Unavailable

The server is temporarily unavailable.
Retry Guide — Wait a few seconds and retry.

​
504 Gateway Timeout

A request exceeded its time budget (code: engine_timeout). On an endpoint that takes a source image, fetching that image is the usual cause.
Retry Guide — Safe to retry with exponential backoff. Credits are automatically refunded on failure.

​
Retrying safely

Only 429 and the 5xx family should be retried. Use exponential backoff: start at one second and double on each attempt (1s → 2s → 4s → 8s), capping at 3–5 tries. If a response includes a Retry-After header, honor it instead. Never retry a 4xx other than 429 — the request is malformed and will fail the same way again.

​
Asynchronous endpoints

Asynchronous partner models return 200 when they accept a job. A job that fails later does not return an HTTP error. The failure appears in the poll response. See Errors and limits on the Partner models overview, and the model page for the error codes of each provider.

​
Credit Safety

If an error occurs after credits have been deducted, they are automatically refunded. You will never lose credits due to a server-side failure.