Docs / Errors

Errors & rate limits

Errors use standard HTTP status codes and a stable machine-readable code.

Error format#

403Response

{
  "error": "forbidden",
  "message": "Fehlender Scope: orders:fulfillment"
}

Branch on error. The message is meant for humans and is currently German.

Status codes#

Status	Code	Meaning
`400`	`bad_request`	Invalid path id, invalid query parameter or invalid JSON body. Detail endpoints, PATCH and POST bodies, and query parameters that are validated (e.g. updated_since).
`400`	`shop_required`	The OAuth token covers several shops and no shop_id was given. Multi-shop OAuth token without shop_id.
`401`	`unauthorized`	API credentials missing, invalid, revoked, or the OAuth access token is expired/revoked. Any endpoint. Response carries header `WWW-Authenticate: Bearer resource_metadata="<origin>/.well-known/oauth-protected-resource"`.
`402`	`feature_not_in_plan`	The shop's subscription plan does not include the feature this endpoint needs (message names the required plan). GET /orders/:id/journey (feature browser_tracking) and GET /revenue (feature reports). Checked BEFORE the scope check.
`403`	`forbidden`	The credential lacks the scope required by the endpoint/field. Scope check per endpoint (and per body field on PATCH /orders/:id).
`403`	`forbidden`	shop_id is not covered by this credential. shop_id query parameter names a shop outside the credential's reach.
`404`	`not_found`	Resource does not exist in this shop. Detail endpoints.
`404`	`not_found`	The shop is deactivated. Any endpoint when the resolved shop has active=false.
`429`	`rate_limited`	More than 600 requests in the current calendar minute for this key/token. Any endpoint. Header `Retry-After` (seconds until the next minute bucket).
`500`	`server_error`	Unexpected server or database error. Some endpoints put the database error text into `message`; others return a generic message ("Die Anfrage konnte nicht verarbeitet werden."). Any endpoint.
`503`	`unavailable`	Per-shop permissions of an OAuth token could not be loaded. OAuth bearer tokens only.
`403`	`subscription_inactive`	The shop's backend is locked because its subscription is not active. Write requests other than PATCH /orders/{id} (today: POST /inventory).
`502`	`refund_failed`	The refund for a cancellation failed; the order keeps its previous status. PATCH /orders/{id} with action "cancel".
`503`	`unavailable`	Filtering by update time is not enabled on the server. GET /orders with updated_since, only while the server has no change tracking.

Rate limits#

600 requests per minute per API key or OAuth token, counted in fixed calendar minutes (UTC).
The limit is shared by the REST API and MCP. On MCP every tools/call counts.
Above the limit you get 429 rate_limited with a Retry-After header (seconds until the next minute).
OAuth endpoints have their own limits: registration 20 per hour and token requests 120 per hour per IP address.

Retrying#

Retry 429, 500 and 503 with exponential backoff and honour Retry-After. Do not retry 400, 401, 402, 403 or 404 without changing the request.