Error codes and rate limits
What each error code means, how rate limits work and how to retry safely.
Gli articoli di assistenza sono disponibili in inglese.
Every error has the same shape: success: false plus an error object containing a code, a human-readable message in your language and a request_id. Codes never change between languages, so build your logic on the code.
Common codes
| Code | HTTP | Meaning | What to do |
|---|---|---|---|
| missing_api_key / invalid_api_key / revoked_api_key | 401 | Key missing, wrong or revoked | Check the X-API-Key header |
| insufficient_credits | 402 | Not enough credits | Buy credits or upgrade |
| plan_limit | 403 | Feature not in your plan, for example video on Free | Upgrade |
| ip_not_allowed / domain_not_allowed | 403 | The key's restrictions blocked the call | Update the key restrictions |
| file_too_large | 413 | Over 22 MB (images) or 200 MB (videos) | Compress or resize |
| invalid_file_type / image_too_large / video_too_long | 422 | Unsupported or too big | Check the limits |
| invalid_image_url | 422 | The URL couldn't be fetched safely | Use a public http(s) URL |
| rate_limit_exceeded / monthly_limit_exceeded | 429 | Too many requests | Wait Retry-After seconds |
| processing_failed / internal_error | 500 | Something failed on our side | Retry; video credits are refunded |
Rate limits
Limits apply per key, per workspace and per IP address. Your plan sets the per-minute limit: 10 on Free, 30 on Starter, 60 on Pro and 120 on Agency. Responses include X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a 429 includes Retry-After.
Retry safely
Retry 429 and 5xx errors with exponential backoff: wait 1 s, then 2 s, 4 s and so on, up to about a minute, adding a little randomness. Don't retry 4xx errors other than 429 without changing the request. When you contact support, include the request_id.
Hai ancora bisogno di aiuto?
Contatta il supporto