Errors

Every error is returned as JSON with the same envelope. The HTTP status code tells you whether you should retry.

HTTP status codes

Code	Meaning	Should you retry?
`200`	OK	—
`400`	Bad request — a required field is missing or invalid, or a filter key is unknown.	No. Fix the request first.
`401`	Missing or invalid credentials, or the IP is not whitelisted for this user.	No. Repeated failed auth locks your IP for 30 seconds.
`403`	Authenticated, but the user is not allowed on this route / method / module.	No. Adjust the user's access controls.
`404`	The document, resource or paginated page does not exist.	Only if you asked for the wrong thing.
`405`	Wrong HTTP method for this endpoint.	No. Fix the method.
`503`	Service temporarily unavailable (e.g. scheduled database maintenance).	Yes, back off exponentially. Start at 5 minutes.
`5xx` (other)	Server-side error.	Yes, with exponential backoff.

Envelope

Errors use the same JSON envelope as success:

{
  "is_error": true,
  "http_code": 400,
  "data": null,
  "messages": [
    "Invalid filter field 'foo'"
  ],
  "request_route": ".../sales/list/foo:bar/",
  "your_ip": "1.2.3.4",
  "your_user": "api_user_xyz",
  "your_method": "GET"
}

Common causes

401 — Unauthorized

Wrong Basic Auth credentials.
Missing Authorization header.
Your IP is not on the user's whitelist.

Failed 401s lock your IP for 30 seconds. Do not retry in a loop — fix the credentials or IP whitelist first.

403 — Forbidden

The API user has a route restriction that excludes the endpoint you called.
The user has a method restriction that excludes the HTTP method you used.
The user has a doctype restriction that does not cover this module.

400 — Bad request

An unknown filter key was passed (e.g. foo:bar). Only the filters documented per endpoint are accepted — others fail fast.
A required JSON body field is missing on a POST or PATCH.
Business rule violated (e.g. registering a payment on a cancelled sale).
Write endpoints list every missing required field at once, naming each one, so you can fix them in a single pass rather than discovering them one retry at a time.

Always check the status code, not just is_error. A rejected write returns 400 (or 500 if the failure was on our side) — never 200. On some endpoints, notably the eCommerce order import, data also carries the payload we received plus an import_summary showing what we actually stored, so you can compare it against what you sent without opening a support ticket.

404 — Not found

The document ID does not exist in your account.
You asked for a page number beyond the last page.
The endpoint path is misspelled.

Retry policy summary

4xx  → do not retry, fix the request
5xx  → retry with exponential backoff (5s, 15s, 45s, ...) up to a few minutes
timeout / network error → retry with backoff, but be idempotent-aware on write endpoints

» Continue to Endpoints.