Errors
Error envelope, status codes and limits.
Errors
Envelope
Errors arrive in a single envelope:
{
"statusCode": 400,
"message": "duration must be an integer number",
}
statusCode— the HTTP code;message— a string or an array of strings (validation errors);code— a machine-readable code (not always present).
Codes
| Code | When |
|---|---|
| 400 | Bad request parameters (DTO validation) |
| 401 | No key / key unknown or deactivated |
| 403 | Legacy service key; access denied |
| 404 | Resource not found |
| 429 | Rate limit exceeded (60/min per partner by default; gateway-wide 100/min per IP). The response carries Retry-After |
| 500 | Internal error — safe to retry later; report to support if it persists |
Validation
The global validation pipeline strips unknown fields and coerces types. The message array lists every violation at once:
{
"statusCode": 400,
"message": [
"duration must be an integer number",
"resolution must be shorter than or equal to 16 characters"
]
}
Retry guidance
- 429 — exponential backoff starting at 1–2 seconds; when the
Retry-Afterheader is present, follow it. - 5xx — retry with a delay; settlements are idempotent on the charging side, but check task status before retrying "launch" endpoints of the generation API.
- 401/403 — do not retry: fix the key.
For AI agents/en/docs/errors.md