Documentation
Errors, limits and retries
Error format, rate limits and idempotency keys.
Error format
Errors use a standard HTTP status and a JSON body:
{
"error": {
"type": "invalid_request_error",
"code": "video_too_long",
"message": "Videos are limited to 15 minutes.",
"request_id": "req_Fq8Kx2LmT9vN3pQa"
}
}Give the request_id (also in the X-Request-Id header) when you contact support.
| Status | Type | Typical codes |
|---|---|---|
| 400 | invalid_request_error |
invalid_json, invalid_parameter |
| 401 | authentication_error |
invalid_api_key |
| 402 | billing_error |
insufficient_credits |
| 403 | permission_error |
plan_required |
| 404 | not_found_error |
job_not_found, upload_not_found |
| 409 | conflict_error |
upload_already_used, idempotency_conflict |
| 413 | invalid_request_error |
video_too_large |
| 422 | invalid_request_error |
unsupported_format, unreadable_video, video_too_long, resolution_too_high, url_not_allowed |
| 429 | rate_limit_error |
rate_limited |
| 500 | api_error |
internal_error |
Rate limits
Limits apply per API key, per method and per endpoint, over one minute:
| Endpoint | Requests per minute |
|---|---|
POST /v1/jobs |
30 |
POST /v1/uploads |
60 |
GET /v1/jobs/{id} |
240 |
| Other endpoints | 120 |
Every response includes X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix seconds). A 429 response includes Retry-After in seconds.
Idempotency
POST /v1/jobs and POST /v1/uploads accept an Idempotency-Key header (up to 255 characters, a UUID is a good choice).
- The same key with the same body returns the original response, with the header
Idempotent-Replayed: true. No second job is created and no extra credits are reserved. - The same key with a different body returns
409 idempotency_conflict. - Keys are kept for 24 hours.
Retry on network errors, 429 and 5xx, with exponential backoff and the same idempotency key.