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": ["Send either scale or width and height, not both."]
    }
}

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, and for an upload group source when it opens and file for its image.

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.
403 pro_required: The call needs a paid plan, Pro or Max: keeping the folder an image came from, responsive_widths, starting a site crawl or a weekly site check, and sharing a page report or downloading it as CSV or PDF come with them. The report itself comes with every scan, and a crawl started on a paid plan can still be read, downloaded and deleted after the plan ends.
403 site_key_not_allowed: The key is a connected site's, made for the WordPress plugin, and opens only that site's calls: its uploads and its settings. Use an API key from Settings > API Tokens for anything else.
403 site_key_required: The call is a connected site's and takes the key made for that site, which the WordPress plugin holds. An API key from Settings > API Tokens does not open it.
403 network_required: The WordPress plugin only, adding a site of a multisite network (POST /site/sites): the key is a site's that was connected on its own, not a network's. Connect the network from the plugin's page in the network admin.
404 not_found: No image, upload group, scan, site crawl or weekly site check with that id on your account, or no such address. An id from another account answers the same way as one that never existed, and so does the id of a file an upload group made: it answers only through its group.
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, or its responsive sizes are still being made, or an upload group still has a file queued or being made. Wait for it to finish, or cancel an image 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, or to write its alt text) and the image has not finished. In a batch call, none of the images named had finished, and a site crawl whose pages compressed no image has no zip. Nor has an upload group whose source has not arrived, or never did.
409 responsive_not_ready: The call downloads an image's responsive sizes and there are none to download: they are still being made, they could not be made, or the image was sent without responsive_widths. The image's responsive.status says which.
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 or site crawl is still running, or one of its images is still being compressed. A weekly site check is stopped only while none of its crawls is running. 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.
409 part_of_crawl: The scan is one page of a site crawl, and a crawl's pages share the images they have in common, so a page cannot be deleted on its own. Delete the crawl it belongs to instead.
409 monitor_limit_reached: Every weekly site check your plan includes is in use. Stop one before starting another.
409 crawl_has_no_pages: A weekly site check is made from a site crawl that scanned at least one page, and this one has none: it is still reading its sitemap, or it failed before scanning any page (its note says why). Wait for it, or crawl the site again and start the check from that crawl.
409 report_not_available: The scan has no page report to share or download: it has not finished, it failed, or it was made before scans measured pages. Wait for it to finish, or scan the page again.
409 group_closed: An upload group takes its source once, within an hour of opening. This one already has it, or its hour to send it passed. Open a new group.
409 site_moved: A connected site's key was used from another address than its site's, as a staging copy or a moved site does. Nothing was done. The WordPress plugin offers to connect the copy as a site of its own or to move the connection to where it now runs.
409 network_full: The WordPress plugin only: the multisite network already has as many sites as one network can, its main site and the sites it disconnected included. Remove a site it no longer uses in Settings > Sites, or connect this one on its own.
409 site_connected_elsewhere: The WordPress plugin only: the site a multisite network tried to add is the network itself, another network, or a site connected to your account on its own or in another network. Nothing changed, and that site's key still works. Disconnect it in Settings > Sites to add it to this network.
409 pairing_pending: The WordPress plugin only, collecting its site key (POST /connect/claim): nobody has approved the connection on iminify.com yet. A pairing that does not exist, or a wrong secret, answers the same way. Ask again every few seconds, until the expires_at the pairing was opened with.
409 uploads_waiting: MCP only: create_upload_link refuses a new link while your uploads not yet compressed reach the images your plan can still compress today, and never more than a fixed number of them. An upload counts from the moment its link is handed out, and a link never used stops counting when it expires. The message names the upload ids already sent: compress them with compress_images, then ask again.
410 pairing_closed: The WordPress plugin only: the connection it is collecting a key for can no longer give one. It expired before it was approved, the person turned it down, or its key was collected already. Press Connect in the plugin again.
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. An upload group's declaration (POST /groups) is held to 64 KB, far more than its largest needs.
422 animation_not_resizable: A resize was asked of an animated WebP or an animated PNG, and Iminify cannot resize their frames: only the first one would be kept. Without width, height or scale, and in its own format, it comes back with every frame. An animated GIF can be resized.
422 outputs_refused: An upload group's outputs break one of its rules: each output at most the source's width and height, one that is not cropped keeping the source's shape, and the limits on how many outputs, how many cropped ones, how large a cropped one, and how many pixels together. The whole group is refused and nothing is counted; the message names the rule.
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. A new upload group is refused this way too while your groups already have many files waiting to be made. 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, page scans, site crawls or AI alt texts for the day are used up, or an upload group would make more files than today has left. Retry-After holds the seconds until the rolling 24-hour window opens again. An image sent while only the alt texts are used up still compresses, without one.
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.
503 download_failed: The file could not be read from storage just now, so nothing was sent. Send the same request again. A zip reads its files while it streams, so a file that fails after the zip has started stops the download short of its Content-Length instead: download the zip again.
503 alt_text_not_available: AI alt text is switched off on the service right now. Images still compress; ask for alt text again later.
400 http_error: Any other HTTP error, with the status it came with.