Errors & status codes
What an error looks like, and what each status code means for your retry.
Standard error shape
A non-2xx response has the body { statusCode, message, error }, for example { "statusCode": 404, "message": "Checkout session not found", "error": "Not Found" }. message is a sentence you can log or show; a request that fails validation can carry a list of what was wrong.
Act on the HTTP status: 400 the request is wrong; 401 the key is missing, wrong or revoked; 403 the key or person may not do this; 404 not found; 409 a conflict with the current state; 422 an Idempotency-Key reused for a different request; 429 too many requests; 5xx a problem on our side, safe to retry with the same Idempotency-Key.
Every response carries an x-request-id header. Quote it when you ask for help.