Errors - Elementary

Every failing request returns a standard HTTP status code and a JSON body with a single error object:

{
  "error": {
    "code": "not_found",
    "message": "Asset 'model.shop.orders' not found."
  }
}

Field	Description
`code`	Stable, machine-readable identifier. Branch on this, never on `message`.
`message`	Human-readable explanation, intended for logs and debugging.

message wording may change at any time; code values are part of the API contract and only change with a new API version. Treat an unrecognized code as a generic failure of its HTTP status class rather than failing hard.

Error codes

Code	Status	When it happens
`invalid_request`	`400`, `422`	A parameter is missing, malformed, out of range (e.g. `limit` above 2000), or two mutually exclusive filters were combined.
`invalid_cursor`	`400`	The `cursor` is not a cursor this API issued, or it is reused with different query parameters than the ones that produced it.
`unauthenticated`	`401`	The `Authorization` header is missing, malformed, or the token is invalid or revoked.
`permission_denied`	`403`	The token is valid but not allowed to read the requested environment or object.
`not_found`	`404`	The environment or object id doesn’t exist — or exists but isn’t visible to this token.
`rate_limited`	`429`	The account exceeded its request limit. See Rate limits.
`internal_error`	`5xx`	Something failed on our side. The request was not necessarily rejected — retry it.

404 is also returned instead of 403 for objects a token can’t see, so that the API doesn’t reveal whether an id exists. A 404 on an id you expect to exist usually means the token’s permissions don’t cover it.

Handling errors

400 / 422 — the request is wrong; fix it and don’t retry as-is. On invalid_cursor, drop the cursor and restart the iteration from the first page with the same filters.
401 / 403 — check the token and its permissions; retrying won’t help.
429 — back off for at least the Retry-After seconds returned with the response before retrying.
5xx — retry with exponential backoff and jitter. Feed requests are idempotent, so replaying a page is safe.

response = requests.get(url, headers=headers, params=params)

if response.status_code >= 400:
    error = response.json()["error"]
    if error["code"] == "invalid_cursor":
        params.pop("cursor", None)  # restart the iteration
    elif error["code"] == "rate_limited":
        time.sleep(int(response.headers.get("Retry-After", 5)))
    else:
        raise RuntimeError(f"{error['code']}: {error['message']}")