Skip to main content
Every error has the same shape, apart from POST /oauth2/token, whose errors follow OAuth 2.0.

Status Codes

Any endpoint that takes a token can answer VALIDATION_FAILED, UNAUTHENTICATED, FORBIDDEN, NOT_FOUND, RATE_LIMITED, INTERNAL_ERROR and SERVICE_UNAVAILABLE, and any that answers with a body can answer NOT_ACCEPTABLE. Handle a 429 from any endpoint: wait for Retry-After, then send the request again.

Unknown Outcomes

A write can lose its answer: a timeout, a dropped connection, a dependency that stopped responding. Two 503 codes tell you what that means for your next step. Only a write with no Idempotency-Key answers OUTCOME_UNKNOWN. Each endpoint that can lists it in the reference, and is in this table: With an Idempotency-Key, a lost answer is always SERVICE_UNAVAILABLE, because the same key and body recover the first attempt’s outcome. See Idempotency.

Safe to Repeat

Some writes take no Idempotency-Key because repeating them does no more than the first call did. Their reference says Safe to repeat, and after SERVICE_UNAVAILABLE you send the same request again. :executeRefund and a capability’s :request can also answer OUTCOME_UNKNOWN, and Unknown Outcomes says what to do for each. GET is always safe to repeat. A repeated DELETE answers 404, which you can treat as success.