HTTP Error Status Codes

When a request fails, the API responds with a non-2xx HTTP status and a JSON body in the following shape:

{
  "code": "BAD_REQUEST",        // stable machine-readable error code
  "message": "Bad Request",     // human-readable description
  "details": {                  // present only on validation errors
    "field": { "message": "..." }
  }
}

Branch on the code field. It is stable and safe to switch on in your application. The message field is intended for humans and may change without notice. The details object is present only for validation errors, and maps each failing field to a message explaining why it was rejected.

Codes

Code	HTTP status	What it means	How to handle
`BAD_REQUEST`	400	The request was malformed or contained invalid input.	Check the request against the endpoint's schema and retry.
`VALIDATION_ERROR`	422	One or more fields failed validation.	Inspect `details` for the offending fields and correct them.
`NOT_AUTHORIZED`	401	Authentication is missing or invalid.	Provide a valid API key or token and retry.
`FORBIDDEN`	403	You are authenticated but not permitted to perform this action, for example when the API key is valid but a related resource is inactive.	Do not retry without the required permissions.
`NOT_FOUND`	404	The requested resource does not exist, or the URL is invalid.	Verify the identifier and URL in the request path.
`NOT_ELIGIBLE`	409	The account or resource is not eligible for this operation, for example a seller service that is still pending approval.	Do not retry until the eligibility requirements are met.
`PAYMENT_DECLINED`	400	The payment was declined.	Use a different payment method and retry.
`PAYMENT_ERROR`	402	Payment is required or could not be completed.	Ensure the account is funded before retrying.

Handling errors

Branch on code, not the HTTP status alone. Multiple codes can share a status. For example, BAD_REQUEST and PAYMENT_DECLINED are both 400.
A 4xx response means something in the request needs to change. Retrying it unchanged will fail again. Fix the input, authentication, or permissions first, then retry.
On a VALIDATION_ERROR, use the details object to pinpoint which fields were rejected and why, rather than parsing the message.