Skip to main content
Every request passes through the IPXO API gateway before it reaches a service. The gateway handles authentication, authorization and rate limiting, so a request can fail before the service ever sees it. Gateway failures and service failures look slightly different, and it is worth being able to tell them apart.

​
Gateway errors

The gateway returns a JSON problem document:
Read title for the human-readable reason and status for the HTTP status code.

​
Authentication and authorization

A missing token returns 400, not 401. This is unusual, and worth handling explicitly if you are branching on status codes.
The WWW-Authenticate header distinguishes the two cases: error="invalid_request" means nothing was sent, error="invalid_token" means what was sent is no longer good. Both are worth retrying only after obtaining a fresh token.

​
Rate limiting

A 429 means you have exceeded the request rate. If the response carries a Retry-After header, wait that many seconds; the value is also interpolated into title. Otherwise back off before retrying.

​
Service errors

Once a request is authenticated and authorized, the service handles it and returns its own status codes:
Error response bodies are not yet uniform across services. Where a service documents a body shape, it is shown on that endpoint’s own reference page — do not assume one shape across all of them. Parse defensively and rely on the HTTP status code as the primary signal.
Some services return a body of the form:

​
Retrying safely

GET requests are safe to retry. For requests that create or modify something — adding a cart line, checking out, creating a ROA — a 500 or a network timeout leaves the outcome unknown. Re-read the resource to check whether the change landed before retrying, rather than sending the same write twice.