API errors

Every error the Iminify API answers with: the JSON shape, the HTTP status, each error code and what to do about it.

Every error comes back in the same shape, with a status code that says what kind of error it is and a code that says exactly which:

JSON

{
    "message": "The compression is still running and cannot be deleted yet.",
    "code": "image_in_progress"
}

message is a sentence you can show a person. Branch on code: messages get reworded, codes don't.

A request that fails validation is a 422 with an errors object naming each field that failed, with its messages:

JSON

{
    "message": "The selected level is invalid. (and 1 more error)",
    "code": "validation_failed",
    "errors": {
        "level": ["The selected level is invalid."],
        "width": ["The width field prohibits scale from being present."]
    }
}

A file or an address that doesn't pass the checks every upload goes through (the format, your plan's file size, the pixel count, an address that can't be fetched) is reported the same way, against the field you sent: file or url.

Status codes

Status	Means
`200`	Done. The body has what you asked for.
`202`	Accepted and queued. Poll the address in `Location`.
`204`	Done, with nothing to send back.
`401`	No key, or a key that doesn't exist.
`403`	The account can't use the API, or this part of it.
`404`	No such image or scan on your account, or no such address.
`409`	The image or scan isn't in a state that allows this yet.
`413`	The request body is too large to accept at all.
`422`	Something in the request is missing or wrong.
`429`	Too many requests, or the day's allowance is spent. Read `Retry-After`.
`500`	Something failed on our side. It has been reported to us.
`503`	Storage hiccupped. Nothing was done or counted; send the same request again.

Error codes

Each code below comes with the status beside it. The endpoints on the reference pages list the codes they can answer with.

401 unauthenticated: No key was sent, or the key does not exist (it was mistyped or deleted). Send it as Authorization: Bearer <key>.
403 email_not_verified: The key belongs to an account whose email address is not verified yet. Follow the link in the verification email, then call again with the same key.
403 account_banned: The account behind the key has been banned. Its keys stop working with the ban.
403 scans_not_available: Your plan does not include page scans.
404 not_found: No image or scan with that id on your account, or no such address. An id from another account answers the same way as one that never existed.
405 method_not_allowed: The address exists but does not take that HTTP method, a PUT where the API expects PATCH, for example.
409 image_in_progress: The image is still queued or being compressed. Wait for it to finish, or cancel it while it is still queued.
409 image_not_cancellable: Only an image still waiting in the queue can be cancelled. This one has started, or already ended.
409 image_not_retryable: Only a failed or cancelled image can be retried. To run a finished one again with other settings, recompress it.
409 image_not_finished: The call needs an optimized copy (to download, rename or zip it) and the image has not finished. In a batch call, none of the images named had finished.
409 image_not_shareable: Only a finished image whose files a browser can show can be shared. A HEIC or TIFF handed back unconverted cannot.
409 scan_in_progress: The scan is still running, or one of its images is still being compressed. Wait for everything to finish.
409 scan_not_cancellable: Only a scan still waiting in the queue can be cancelled.
409 scan_not_retryable: Only a failed or cancelled scan can be retried.
413 payload_too_large: The request body is over 100 MB, the most any request can carry. A body that large may be turned away before it reaches the API, and then the 413 is not JSON. Your plan's file size limit is lower and is answered with validation_failed.
422 validation_failed: A field is missing or wrong, or the file or address did not pass the checks every upload goes through. errors names each field with its messages.
429 rate_limited: One of your per-minute limits is spent: requests, compressions or page scans. The compressions and scans are counted together with the website's, so work queued there counts too. Nothing was done; wait for the number of seconds in the Retry-After header and send it again.
429 daily_limit_reached: Your plan's images or page scans for the day are used up. Retry-After holds the seconds until the rolling 24-hour window opens again.
500 server_error: Something failed on our side. It has been reported to us. Try again in a moment.
503 start_failed: The file could not be stored or queued, usually a short hiccup at the storage. Nothing was counted. Send the same request again.
503 delete_failed: The files could not be removed from storage just now, so nothing was deleted. Send the same request again.
400 http_error: Any other HTTP error, with the status it came with.