Errors and rate limits
Error format, status codes, and staying within limits.
Error format
All errors return a JSON body with a machine-readable code and a human-readable message:
{
"error": {
"code": "invalid_request",
"message": "The task field is required.",
"param": "task"
}
}Status codes
| Code | Meaning | Notes |
|---|---|---|
| 400 | Malformed request | Invalid JSON, wrong multipart encoding. |
| 401 | Missing or invalid API key | Check the Authorization header. |
| 402 | Insufficient credits | Out of balance or past a spend limit; top up in the dashboard. |
| 404 | Not found | Unknown design/file ID or route. |
| 413 | Request too large | Uploads are limited to 50 MB per file. |
| 422 | Unprocessable request | Invalid parameters. |
| 429 | Rate limited | See below; retry with backoff. |
| 500 | Internal error | Retry with backoff; tell us if it persists. |
Error codes
Prop
Type
Rate limits
Limits are per-organization and scale with your plan; they exist to protect the platform from runaway loops, not to constrain real workloads. Concurrent request limits are configurable from the dashboard.
When you hit a limit you'll receive 429 with a retry_after hint in the error message. Retry with exponential backoff when you see it.
Designing within limits
Batch jobs (like the batch content guide) should use bounded concurrency — e.g. 4–8 parallel requests — rather than unbounded fan-out. It's friendlier to the platform and to your budget.
Idempotency and retries
API requests are not idempotent by default: a retried POST /design creates a second design. Retry only on connection errors and 429/5xx responses, with backoff. If you need exactly-once semantics in your pipeline, keep track of the design IDs you receive and check GET /design/{id} before re-sending.