Skip to Content

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).
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" }
  }'

Rate limits & concurrency

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

HeaderMeaning
x-ratelimit-limitAllowed submissions per minute for your account
x-ratelimit-remainingRemaining submissions in the current window
x-ratelimit-resetSeconds until the current window resets
retry-afterSeconds 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

On this page

For AI agents

This page as Markdown: /docs/idempotency-limits.md

Everything at once: /llms-full.txt