Skip to content

Errors

The error envelope, the status codes API v3 returns, and the code to branch on for each.

Last updated

Every error has the same JSON body. Branch on code, show errors to people.

{
"errors": ["This shop keeps issued invoices unchanged (lock invoices after issue), so the order data cannot be regenerated."],
"code": "invoice_locked"
}

code is missing on some validation errors. errors is always present.

Status code Meaning What to do
401 unauthorized No X-Auth-Token, an unknown key, or the store uninstalled the app. Check the key. See Authentication.
403 v3_required The store still uses the previous dashboard. Use API v1 until the store moves.
403 paid_plan_required The store’s plan doesn’t include API access. The store needs a paid plan.
404 not_found No such record in this store, or no action at this path and method. Check the id and the path in the reference.
409 confirmation_required A permanent change needs confirmation. Nothing changed. Repeat with confirm. See Confirming permanent changes.
409 invoice_locked, stale_next_invoice_number and others The request conflicts with the current state, for example the store locks issued invoices. Nothing changed. Read the record again, then decide.
422 unmapped_settings, invalid_settings, invalid_date, blank_value and others, or none Validation failed. Nothing saved. Fix the request. The message names the field.
429 rate_limited Over the rate limit. Wait retry_after seconds. See Rate limits.
429 bulk_action_in_progress A bulk job is already running for this store. Wait for it, or cancel it with POST /documents/bulk/:job_id/cancel.
502 shopify_error Shopify didn’t answer. Retry later with backoff.

Each action’s page in the reference lists the statuses it can return.

Was this page helpful?

Still stuck? Ask Quinn or chat with support