Errors and limits
Every error has the same shape: {"error": {"code": "…", "message": "…"}}. The code does not change; the sentence is for people to read, always in English, and may change.
| HTTP | code | Meaning |
|---|---|---|
| 400 | malformed, malformed_json, invalid_idempotency_key | The request body cannot be read, or the Idempotency-Key is not 1 to 255 characters. |
| 401 | api_credentials_required, invalid_api_key, access_token_required, invalid_access_token, access_token_expired | No access token (api_credentials_required); the client ID and secret were sent in place of an access token (access_token_required, both only for POST /v1/token); or the token is wrong, revoked, or expired. Request a new token. |
| 402 | insufficient_credit, queue_full, not_on_plan | The shop's balance is not enough for this or for the queue of reads already waiting (top up first), or the shop's plan does not include the API. |
| 403 | missing_scope, not_available_to_api, scan_off | This integration does not have the permission, that part is not open to the API, or AI scanning is not switched on on this server. |
| 404 | not_found | Does not exist, or belongs to another shop. |
| 409 | too_many_pending, already_reported, already_decided, top_up_cancelled, read_in_progress, type_off, duplicate_name, idempotency_request_in_progress | The current state does not allow that request now, or the first request with the same Idempotency-Key is still being answered. |
| 422 | invalid, model_not_offered, file_kind, no_fields, pdf_too_many_pages, pdf_unreadable, page_out_of_range, over_max_charge, document_keeps_failing, too_many_pages, knowledge_full, invalid_amount, idempotency_key_reused, event_not_allowed | The request content is wrong. The message says what needs fixing. |
| 429 | rate_limited, too_many_running, too_many_failures, scan_limit | Over the per-minute request limit (wait as long as Retry-After says), 10 articles being written or 10 images being made, too many failed reads today, or today's 20 scans are used up. |
| 503 | ai_unavailable, no_model, top_up_unavailable, secrets_key_missing | No AI model can be used, top-ups are not available yet, or this server cannot sign webhooks yet. |
- The per-minute request limit is set by the shop per integration (default 60). Every response carries X-RateLimit-Limit and X-RateLimit-Remaining.
- An access token is valid for 15 minutes.
- The response for an Idempotency-Key is kept for at least 24 hours; 5xx responses are not kept, so a retry runs again.