API problem types
Every error from the API is an application/problem+json document (RFC 7807). Its type field is a URL on this page, so an error response links directly to its explanation. The detail field describes the specific cause, and requestId identifies the request for support. Failed requests are never billed a credit.
/docs/problems/file-required
The request reached the API without an image. The optimize endpoint expects one image in the multipart form field named "file".
/docs/problems/invalid-multipart-request
The multipart request contained more than one file or more form fields than the endpoint accepts.
/docs/problems/invalid-idempotency-key
The Idempotency-Key header was present but malformed. Keys must contain 1-255 visible ASCII characters.
/docs/problems/insufficient-credits
No unexpired API credits remain on the account. Processing stops rather than billing overage automatically.
/docs/problems/processing-timeout
Image processing exceeded the 30 second deadline and was cancelled. No credit was charged.
/docs/problems/request-in-progress
Another request with the same Idempotency-Key is still processing.
/docs/problems/request-already-completed
A request with this Idempotency-Key already completed. Image bytes are not retained, so the earlier result cannot be replayed — this protects you from a double charge, not from data loss.
/docs/problems/image-too-large
The encoded file exceeds 20 MB, or the decoded image exceeds 25 megapixels.
/docs/problems/unsupported-input-format
The uploaded bytes are not one of the supported input formats. Detection reads the file content, not the filename.
/docs/problems/unsupported-output-format
The requested output format is not available on the server that handled the request (for example AVIF encoding on a deployment without an AVIF encoder).
/docs/problems/email-domain-not-allowed
Sign-in was requested with a disposable email address. Because free monthly API credits are granted per account, throwaway inboxes are refused.
/docs/problems/invalid-image
The file could not be decoded. It is corrupt, truncated, or not actually an image.
/docs/problems/idempotency-key-conflict
This Idempotency-Key was already used with a different request body or parameters.
/docs/problems/rate-limit-exceeded
The account reached its per-minute request limit. The response carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After headers.
/docs/problems/concurrency-limit-exceeded
The account reached its limit of simultaneously processing requests. The response carries a Retry-After header.
/docs/problems/internal-server-error
Something failed on our side. No credit is charged for failed requests.
Generic problem types
Errors without a dedicated type — request validation, for example — use /docs/problems/http-<status> (such as /docs/problems/http-400). The response body's detail field carries the specific cause.
See the API documentation for request parameters and response headers, or API status for live capabilities.