Every API error uses one envelope. code is stable and safe to branch on; message is for people and may change; details is optional structured context. Every response carries x-request-id; include it when you contact support.
429 after Retry-After, and 503 with exponential backoff.4xx without changing the request.status becomes failed with an error_code (see the upload flow).Img2siteError (server) and Img2siteUploadError (browser) with the same status, code and details.Error envelope
HTTP/1.1 413 Payload Too Large
x-request-id: 0f6c…
{
"error": {
"code": "file_too_large",
"message": "…",
"details": { "max_bytes": 100000000 }
}
}| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | The body or query failed validation (unknown fields are refused). details says which field. |
| 400 | invalid_json | The body is not valid JSON. |
| 400 | invalid_cursor | A pagination cursor was altered or truncated. Restart from the first page. |
| 400 | invalid_file_slug | file_slug must match ^[a-z0-9][a-z0-9._-]{0,127}$. |
| 400 | invalid_transform_chain | The chain does not parse or names an unknown preset; details.reason says why. |
| 400 | watermark_preset_not_found | A watermark preset named in a chain or setting does not exist in this project. |
| 400 | transform_chain_not_allowed | Minting a signed URL on a public project with a chain outside allowed_transform_chains. |
| 400 | invalid_range | Usage from must be before to. |
| 401 | unauthorized | Missing, unknown or revoked credential. |
| 403 | forbidden | The API key lacks the scope this operation needs. |
| 403 | browser_session_required | This route is for dashboard sessions only (keys, settings, billing, audit). |
| 403 | project_suspended | The project is suspended. |
| 403 | project_suspended_by_staff | Only img2site staff can reactivate this project. |
| 403 | storage_quota_exceeded | The upload would exceed the project's storage limit. |
| 403 | raw_download_disabled | A raw signed URL was requested but the project has raw downloads off. |
| 404 | not_found | The resource does not exist or belongs to another project or organization. |
| 404 | file_not_found / upload_not_found | No such file or upload session in this project. |
| 409 | project_exists | The project slug is taken. |
| 409 | api_key_quota_exceeded | The project already has 100 active API keys. |
| 409 | file_not_ready | The file is not ready (for example blocked). |
| 409 | signing_key_missing | The project has no active signing key; rotate one. |
| 409 | default_watermark_in_use | The preset is the project's default watermark; change the default first. |
| 409 | recipe_name_taken | Another recipe of the project has this name. |
| 413 | payload_too_large | The request body is over the route's limit (64 KiB for most writes). |
| 429 | rate_limited | Too many requests or failed authentications; wait for Retry-After seconds. |
| 503 | auth_unavailable / storage_unavailable | A dependency is briefly unavailable. Retry with backoff. |
| Status | Code | Meaning |
|---|---|---|
| 400 | unsupported_content_type | content_type is not one of the supported image types. |
| 400 | invalid_part_size / parts_required | Multipart parts are smaller than 5 MiB, or complete was called without the part list. |
| 400 | invalid_parts | The multipart part list is not every part 1..N once with a non-empty ETag, names parts not uploaded, has a part other than the last under 5 MiB, or does not add up to size_bytes. The upload is left as it was; send the full list. |
| 400 | multipart_complete_failed | The storage backend refused to assemble the parts (for example a wrong ETag); details.reason. |
| 400 | body_length_mismatch | The proxy PUT sent fewer bytes than size_bytes. |
| 401 | invalid_signature / signature_expired | The proxy PUT URL was altered, or is past its exp (the session's 15 minutes). Create a new session. |
| 409 | ingest_object_missing | Complete was called before the bytes arrived. |
| 409 | ingest_size_mismatch | The stored object is not size_bytes long. |
| 409 | upload_not_pending | The session is already past the step you called. |
| 411 | length_required | The proxy PUT has no Content-Length. |
| 413 | file_too_large | size_bytes is over the upload limit (details.max_bytes). |
| 415 | content_type_mismatch | The proxy PUT's Content-Type differs from the session's. |
| 422 | sha256_mismatch | The bytes do not match the declared sha256. |
Delivery hosts answer 404 not_found for anything they cannot serve and 403 with project_suspended, quota_exceeded, file_blocked, signature_required, invalid_signature, signature_expired, unknown_kid or transform_chain_not_allowed. The delivery guide lists them in the order they are checked. Use a placeholder image when a delivery URL fails.