# Idempotency & limits

> Safe retries with Idempotency-Key, per-minute rate limits, the cap on tasks in progress, and payload limits.

## Idempotent task creation

`POST /v1/tasks` supports an optional `Idempotency-Key` header (up to 255 characters, such as a UUID or your order ID).

- **Same key, same body within 24 hours**: Returns the original task object with HTTP `200` (a new task is `201`), without creating a duplicate task or holding balance twice.
- **Same key, different body within 24 hours**: Returns HTTP `409` (`idempotency_conflict`).

```bash
curl -X POST https://api.kerox.ai/v1/tasks \
  -H "Authorization: Bearer $KEROX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-a1001-shot-1" \
  -d '{
    "model": "bytedance/seedream-5.5",
    "input": { "prompt": "a quiet coastal lighthouse at dusk", "size": "2K" }
  }'
```
```python
import os
import uuid
import requests

resp = requests.post(
    "https://api.kerox.ai/v1/tasks",
    headers={
        "Authorization": f"Bearer {os.environ['KEROX_API_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "model": "bytedance/seedream-5.5",
        "input": {"prompt": "a quiet coastal lighthouse at dusk", "size": "2K"},
    },
    timeout=30,
)
print(resp.json())
```
```javascript

const res = await fetch('https://api.kerox.ai/v1/tasks', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KEROX_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    model: 'bytedance/seedream-5.5',
    input: { prompt: 'a quiet coastal lighthouse at dusk', size: '2K' },
  }),
});
console.log(await res.json());
```

## Rate limits & concurrency

`POST /v1/tasks` returns rate-limit headers on every response:

| Header | Meaning |
| --- | --- |
| `x-ratelimit-limit` | Allowed submissions per minute for your account |
| `x-ratelimit-remaining` | Remaining submissions in the current window |
| `x-ratelimit-reset` | Seconds until the current window resets |
| `retry-after` | Seconds to wait, on HTTP `429` `rate_limited` |

A second limit caps the tasks you can have in progress at once (`queued` or `running`). Over it, `POST /v1/tasks` returns HTTP `429` `concurrency_limited`: wait for a task to finish, then submit again.

Uploads have their own limit: `POST /v1/files` accepts 60 uploads per minute per account. Over it, the response is HTTP `429` `rate_limited` with `retry-after`. A higher per-minute ceiling per IP address also applies to submissions and uploads.

`GET /v1/account` shows both task limits (`limits.max_per_minute`, `limits.max_concurrent`) and the number of tasks in progress (`running_tasks`).

## Size limits

- **JSON request body**: ≤ 4 MB
- **Inline base64 data URIs**: ≤ 3 MB combined per request (use `POST /v1/files` for larger inputs)
- **Direct multipart file upload**: ≤ 4 MB
- **Presigned file upload (`/v1/files`)**: ≤ 200 MB
- **Task `metadata` JSON**: ≤ 4 KB
