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

# Rate Limits

> Per-plan caps on requests per minute and simultaneous jobs, which requests count toward each, and how to back off from a 429.

# Rate Limits

### Understand and manage how many requests you can run simultaneously on Nunchux

## Plan Limits

Every API key belongs to a plan. The plan sets two independent caps: requests per minute, and simultaneous jobs.

| Plan | Requests per Minute | Simultaneous Jobs |
| - | - | - |
| Free | 60 | 5 |
| Pro | 200 | 10 |
| Enterprise | 600 | 20 |

## Checking Your Caps

Read your own caps at any time from `GET /v1/credits`, which takes no parameters and returns your own account only. It uses the same API key for [authentication](/authentication) as every other endpoint.

<CodeGroup>
  ```bash curl theme={"system"}
  curl https://api.nunchux.ai/v1/credits \
    -H "X-API-Key: $NUNCHUX_API_KEY"
  ```

  ```python python theme={"system"}
  import os
  import requests

  response = requests.get(
      'https://api.nunchux.ai/v1/credits',
      headers={'X-API-Key': os.environ['NUNCHUX_API_KEY']},
      timeout=30,
  )
  response.raise_for_status()

  print(response.json())
  ```
</CodeGroup>

A `200` carries the balance and the caps that apply to your plan. The API returns [standard error codes](/errors) with a JSON error body.

```json theme={"system"}
{
  "credits_remaining": 96.49,
  "plan_level": "pro",
  "rpm_limit": 200,
  "concurrent_limit": 10
}
```

| Field | Type | Description |
| - | - | - |
| `credits_remaining` | number | Credits left on the account. One credit is \$1.00. |
| `plan_level` | string | The plan the account is on. Each plan has its own caps. |
| `rpm_limit` | number | Requests per minute this plan allows. |
| `concurrent_limit` | number | Simultaneous jobs this plan allows. |

<Note>
  Polling

  This poll is free and it never takes a job slot. It still counts toward your requests per minute.
</Note>

## What Counts

Every authenticated request counts toward requests per minute, polls included. Only requests that start a generation take a job slot, and how long they hold it depends on the kind of request.

| Request | Requests per Minute | Job slot |
| - | - | - |
| Async submit: Kling, Veo 3.1, HeyGen | Counts | Takes a slot. A rejected submit does not. |
| Synchronous generation: `/v1/images/*`, `/v1/videos/*` | Counts | Holds a slot for the duration of the request. |
| Nano Banana: `/v1/google/v1beta/interactions` | Counts | No slot. The call is synchronous and returns in seconds. |
| Status polls | Counts | No slot. |
| Account reads: `GET /v1/credits`, `GET /v1/discounts`, `GET /v1/heygen/v3/voices` | Counts | No slot. |

## When You Hit a Limit

The API returns a `429` for both caps. The error code says which cap you hit.

### Requests per Minute

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

<Note>
  What to do

  Wait, then retry with exponential backoff: 1s, 2s, 4s, 8s. Cap at five attempts. Spreading submits evenly over the minute avoids it altogether.
</Note>

### Simultaneous Jobs

```json theme={"system"}
{
  "error": {
    "code": "concurrent_limit_exceeded",
    "message": "Concurrent job limit reached. Wait for a running job to finish, then retry."
  }
}
```

<Note>
  What to do

  Retrying quickly will not help. Wait, poll your running jobs, and submit again once one has completed.
</Note>

The full error contract is on the [Errors](/errors) page.


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