Errors

How a failure looks, what each status means and when to retry.

Overview

O2M uses standard HTTP status codes. Every failure explains itself in a JSON body, and many carry a fixed code your software can act on.

Error format

A failed request answers with a status of 400 or above and a JSON body. message is written for people. code, when present, is stable and safe to use in your code.

Response 422

{
  "message": "No item has SKU GHOST",
  "code": "UNKNOWN_SKU",
  "skus": [
    "GHOST"
  ]
}

Field	Type	Description
`message`	string	What went wrong. Always present. Do not match on this text: it can change.
`code`	string	A fixed code. Present on the errors listed in these pages.
`skus`	array	With `UNKNOWN_SKU` and `NOT_YOUR_SKU`: every SKU at fault.
`requiredPermission`	string	With a missing permission: what the key lacks.
`retryAfterSeconds`	number	With `RATE_LIMITED`: the seconds to wait.
`requestId`	string	With an invalid or oversized body: the request's reference.

A problem in the lines of a request names the line, counting from 1, for example Line 2: sku is required.

Status codes

Status	Meaning	Retry?
200	It worked.	No need
201	It worked and something was created.	No need
400	The body is not valid JSON.	Fix it first
401	The key is missing or not accepted.	Fix it first
403	The key may not do this, or the feature is not enabled.	Fix it first
404	It does not exist, or this key may not see it.	Fix it first
409	It conflicts with how things stand now, such as cancelling a shipped order.	Only after the situation changes
413	The request is too large.	Make it smaller
422	Something in the request is wrong. `message` says what.	Fix it first
429	Too many requests.	Yes, after `Retry-After`
500	O2M could not finish the request.	Yes, with an Idempotency-Key
503	O2M could not check the key for a moment.	Yes, after a short wait

Common errors

Any endpoint can return these.

Status	Code	Message	What to do
400	—	A description of the JSON problem	Send valid JSON.
401	`NO_API_KEY`	Send your access key in the X-Access-Key header and your secret key in the X-Secret-Key header	Add the secret key.
401	`NO_ACCESS_KEY`	Send your access key in the X-Access-Key header, beside the secret key. It is shown in Settings → API keys.	Add the access key.
401	`INVALID_API_KEY`	This access key and secret key are not valid together, or the key was revoked or has expired	See why a key stops working.
403	`COMPANY_INACTIVE`	Company account is suspended or terminated	Contact your O2M account manager.
403	`MODULE_NOT_ENABLED`	The public API is not enabled for your company by the platform administrator	Ask your O2M account manager to enable it.
403	—	Access denied, with `requiredPermission`	Give the key that permission by making a new key.
404	—	Not found	Check the path. It may be wrong, or the ID malformed.
413	—	request entity too large	Keep the body under 100 KB. Split large requests.
429	`RATE_LIMITED`	Too many requests: this key may make 120 a minute. Try again in 30 seconds.	Wait `Retry-After` seconds. See Rate limits.
500	—	Unable to …, naming what failed	Retry. If it keeps failing, contact support with the `X-Request-Id`.
503	`UNAVAILABLE`	Unable to verify the API key. Please retry.	Retry after a short wait.

A missing permission

requiredPermission names what the key lacks. A key's permissions cannot be changed, so make a new key that includes it. The permissions table shows which box to tick.

Response 403

{
  "error": "Forbidden",
  "message": "Access denied.",
  "requiredPermission": "orders:read"
}

Handle errors in your code

Log the status, code, message and the X-Request-Id header of every failure.
Retry only 429, 500 and 503, waiting longer each time.
Send an Idempotency-Key on creating requests, so a retry can never do the work twice.
Look up a failed request in the API logs.