> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nunchux.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Authenticate every request with your API key in the `X-API-Key` header or `Authorization: Bearer`. Keys start with `sk-nunchux-`.
> Image generation is synchronous: the image is in the response.
> Video generation is asynchronous: submit the job, poll its task until it reaches a terminal status, then download the output promptly, because output URLs expire.

# Errors

> API error codes, response formats, and retry guidance for the Nunchux API.

# 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.

| Field | Type | Description |
| - | - | - |
| `error.code` | string | A machine-readable error code (e.g. invalid\_api\_key, rpm\_limit\_exceeded). Use this for conditional logic. |
| `error.message` | string | A human-readable description of the error. Display this to end-users. |
| `detail` | string | Request-validation failures (unknown model, bad parameters) return this plain string instead of an error object. |

## 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.

```json theme={"system"}
{
  "detail": "unknown model 'invalid-model'; allowed values: nunchux-qwen-image-2512, nunchux-flux.2-klein-9b, ..."
}
```

<Warning>
  Retry Guide — Do not retry. Fix the request parameters before resending.
</Warning>

### 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).

```json theme={"system"}
{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid or revoked API key."
  }
}
```

<Warning>
  Retry Guide — Do not retry. Check that your API key is correct and active.
</Warning>

### 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.

```json theme={"system"}
{
  "detail": {
    "code": "model_not_available",
    "message": "Model nunchux-flux.2-klein-9b is restricted on this account",
    "model": "nunchux-flux.2-klein-9b",
    "entrypoint": "nunchaku"
  }
}
```

<Warning>
  Retry Guide — Do not retry. Use a public model, or contact support to request
  access.
</Warning>

### 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.

```json theme={"system"}
{
  "error": {
    "code": "rpm_limit_exceeded",
    "message": "Rate limit exceeded. See the rate-limit response headers for your limit and reset time."
  }
}
```

<Warning>
  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.
</Warning>

### 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.

<Info>
  Credit metadata

  The 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.
</Info>

| Field | Type | Description |
| - | - | - |
| `error.code` | string | Always "insufficient\_credits". |
| `error.message` | string | A human-readable description of the error. Display this to end-users. |
| `error.request_id` | string | Correlation id for this request. Always present. |
| `error.details.credits_required` | number | The credits this request needs. Not always included. |
| `error.details.credits_balance` | number | Your credit balance. Not always included. |
| `error.creditsRequired` | number | Deprecated mirror of error.details.credits\_required. |
| `error.creditsBalance` | number | Deprecated mirror of error.details.credits\_balance. |

```json theme={"system"}
{
  "error": {
    "code": "insufficient_credits",
    "message": "Your account does not have enough credits for this request.",
    "request_id": "<your-request-id>",
    "details": {
      "credits_required": 0.005,
      "credits_balance": 0.002
    },
    "creditsRequired": 0.005,
    "creditsBalance": 0.002
  }
}
```

<Warning>
  Retry — Do not retry. Check your credit balance and purchase more credits if
  needed. See [Credits & Pricing](/credits-pricing).
</Warning>

## 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.

```json theme={"system"}
{
  "detail": "Inference failed: <upstream response body>"
}
```

## Server Error Codes

### 500 Internal Server Error

An unexpected error occurred on the server.

<Warning>
  Retry Guide — Safe to retry with exponential backoff. Credits are
  automatically refunded on failure.
</Warning>

### 502 Bad Gateway

The inference service returned no data. The request was processed but no output was generated.

<Warning>
  Retry Guide — Safe to retry with exponential backoff. Credits are
  automatically refunded on failure.
</Warning>

### 503 Service Unavailable

The server is temporarily unavailable.

<Warning>Retry Guide — Wait a few seconds and retry.</Warning>

### 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.

<Warning>
  Retry Guide — Safe to retry with exponential backoff. Credits are
  automatically refunded on failure.
</Warning>

## 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](/partner-models/overview#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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.