​
Status codes

StatusMeaning
200 / 201Success
400Malformed request — missing/invalid fields (details in the error message)
401Missing or invalid API key
404Resource not found, or it belongs to another account
409Conflict (e.g. Idempotency-Key reuse with a different body)
422Request understood but not processable (e.g. expired session)
5xxSwitchFlow-side failure — safe to retry with the same Idempotency-Key

​
Error envelope

Errors return a JSON body with a stable machine-readable code and a human-readable message: 
{
  "error": {
    "code": "validation_failed",
    "message": "amountMinor must be a positive integer"
  }
}
Branch on error.code, not on message — messages may be reworded.

​
Common codes

CodeWhereMeaning
validation_failedAny endpointA request field failed validation
token_expiredPayment submissionThe vault token or session expired — the widget re-collects the card automatically
session_expiredPayment submissionThe payment session passed its expiresAt — create a new session

​
Payment outcomes are not HTTP errors

A declined card is a successful API call with a decline outcome — you get 200 with status: "DECLINED" and a normalized declineCode, not a 4xx. Reserve your HTTP-level error handling for integration problems, and read payment outcomes from the response body and webhooks.