Concepts
Errors
Errors use standard HTTP status codes and one JSON shape, so one handler covers every endpoint.
{
"error": {
"code": "invalid_request",
"message": "Some fields are missing or invalid.",
"details": [{ "path": "product_name", "message": "Too short" }],
"request_id": "3f6c1a52-8d0e-4c1b-9a51-2f3e4d5c6b7a"
}
}Branch on code; message is written for a person. details lists field problems as path and message. Every response carries an X-Request-Id header; include it when you write to us.
Codes
| Status | Code | Meaning |
|---|---|---|
400 | invalid_request | Something in the request is missing or wrong. details says what. |
401 | unauthorized | No key, an unknown key, or an expired or revoked one. |
403 | insufficient_scope | The key doesn’t have the permission this needs. |
403 | licence_required | The workspace has no Business licence for this tool. |
403 | forbidden | The key’s creator can no longer do this, e.g. they became a viewer. |
404 | not_found | Nothing with that id in your workspace, or no such endpoint. |
405 | method_not_allowed | The endpoint exists but not with this method. |
409 | conflict | E.g. an idempotency key reused with a different body. |
429 | rate_limited | Too many requests. Wait Retry-After seconds. |
429 | allowance_exceeded | The tool’s daily or monthly allowance is used. |
429 | concurrency_limit | Too many jobs running at once, e.g. two briefs already. |
500 | internal_error | Our side. Safe to retry with the same idempotency key. |
503 | service_unavailable | Briefly unavailable. Retry after a short wait. |
503 | queue_unavailable | The job was saved but not queued. Retry with the same key. |
A 401 also carries a WWW-Authenticate header.