Errors
The error envelope, the status codes API v3 returns, and the code to branch on for each.
Last updated
API v3
invoicefalcon.comContactTermsinvoicefalcon.com
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?
Thanks for letting us know.
Still stuck? Ask Quinn or chat with support