Error codes and rate limits
What each error code means, how rate limits work and how to retry safely.
帮助文章以英文提供。
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.
仍需要帮助？
联系支持