Errors - Admin API (v0)

Every error uses the same JSON shape:

{
  "error": {
    "code": "invalid_parameter",
    "message": "Human-readable explanation",
    "request_id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
  }
}

code is stable — branch on it.
message is informational and may be reworded; don't parse it.
request_id identifies the exact request in our logs. Quote it when you contact support.

Status codes

Status	`code`	When
`400`	`bad_request`	A filter value couldn't be parsed (e.g. a non-date passed to a date filter).
`401`	`unauthorized`	API key missing, malformed, expired, or revoked.
`401`	`unauthorized`	The key is a Storefront API key. The Admin API takes only admin keys (`admin_sk_…`).
`403`	`forbidden`	The key is valid but lacks the permission the endpoint needs (e.g. `orders:read`).
`404`	`not_found`	The resource doesn't exist — or belongs to another organization.*
`422`	`invalid_parameter`	A well-formed parameter was semantically invalid: an inverted `from`/`to` range, or an unknown enum value (e.g. an unsupported `sales_channel`).
`422`	`unprocessable`	A required parameter was missing.
`429`	`rate_limited`	Per-key rate limit exceeded. Respect the `Retry-After` header.
`500`	`server_error`	Something went wrong on our side. Safe to retry with backoff; quote the `request_id`.

* Cross-organization access is deliberately indistinguishable from "not found", so a key can't probe for the existence of another organization's records.

Examples

Unparseable filter (400):

{ "error": { "code": "bad_request", "message": "created_from must be an ISO 8601 timestamp", "request_id": "…" } }

Inverted range (422):

{ "error": { "code": "invalid_parameter", "message": "created_from must be before created_to", "request_id": "…" } }

Missing permission (403):

{ "error": { "code": "forbidden", "message": "This API key lacks the orders:read permission", "request_id": "…" } }

A key without the permission gets 403 whether or not the record exists, so it can't probe for records it may not read.

Rate limited (429, with Retry-After: 60):

{ "error": { "code": "rate_limited", "message": "Too many requests; slow down and retry after the window", "request_id": "…" } }