Reliability/12 of 24
Errors
HTTP status codes, stable error codes, and request IDs.
Errors use HTTP status codes and a JSON body with a stable code and a message. Failed images are not charged.
Every response has X-Request-Id. Include it when you contact support.
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | A parameter is missing or has the wrong value, or a file can't be read. |
| 400 | cannot_shrink | Compress couldn't produce a smaller file (often because stripping EXIF/XMP/IPTC would be the only change). Send keep_metadata=true, lower quality, or resize. |
| 401 | unauthorized | The API key is missing, wrong or revoked. |
| 402 | limit_reached | Free plan: this month's images and your pack images are used up. |
| 402 | overage_cap_reached | Pro or Business: you've reached the extra-image cap set on your account. |
| 403 | plan_required | lossless, a numeric quality, or target_kb on the Free plan. |
| 404 | not_found | The job doesn't exist or has expired (after 1 hour). |
| 413 | file_too_large | A file is bigger than your plan allows. |
| 415 | unsupported_format | A type we can't read or write, such as SVG, camera RAW, JPEG XL or HEIC output. |
| 422 | too_many_files | More files than your plan allows in one request. |
| 422 | processing_timeout | An image took longer than its time limit. Try a smaller maxWidth, another format, or no target_kb. |
| 429 | rate_limited | Too many requests this minute. Retry after the seconds in Retry-After. |
| 500 | server_error | Something went wrong on our side. Nothing was charged. |
| 503 | busy | We're at capacity. Retry after the seconds in Retry-After. |
| 503 | shutting_down | Temporary unavailability during maintenance. Retry after Retry-After. |
Error response
HTTP/1.1 413 Payload Too Large
X-Request-Id: 2b7d0f4e-91c3-4a8e-b5f2-6d1e3c9a7f04
{
"error": "team-offsite.jpg is larger than 25 MB",
"code": "file_too_large",
"message": "team-offsite.jpg is larger than 25 MB"
}