Status Codes

The Payouts API uses conventional HTTP status codes to indicate the outcome of a request. In general:

2xx - the request succeeded.
4xx - the request failed because of something in the request (a missing field, an invalid value, a conflict with existing state, or an authentication or authorization problem). These are safe to surface to the caller and, once corrected, safe to retry.
5xx - something went wrong on our side. The request may or may not have been processed; use idempotency keys so retries are safe.

Every 4xx and 5xx response carries a structured error body. See Errors for the response shape and the full list of error types and codes.

Success codes

Status	Meaning	When you’ll see it
`200 OK`	The request succeeded and the response body contains the result.	Reads (`GET`) and updates that return the affected resource.
`201 Created`	A new resource was created.	`POST` endpoints that create an entity (accounts, payments, and so on).
`202 Accepted`	The request was accepted for asynchronous processing.	Operations that complete out of band; the final state is delivered via webhooks.
`204 No Content`	The request succeeded and there is no response body.	Deletes and some updates.

Status	Error type	Meaning
`400 Bad Request`	`invalid_request_error`	The request was malformed or a field failed validation.
`401 Unauthorized`	`authentication_error`	Credentials are missing or invalid.
`403 Forbidden`	`authorization_error`	The credentials are valid but not permitted to perform this operation.
`404 Not Found`	`not_found_error`	The requested resource does not exist.
`409 Conflict`	`conflict_error`	The request conflicts with the current state of the resource.
`429 Too Many Requests`	`rate_limit_error`	Too many requests were sent in a given window. Back off and retry.
`500 Internal Server Error`	`internal_error`	An unexpected error occurred on our side.
`503 Service Unavailable`	`service_unavailable_error`	A dependency is temporarily unavailable. Retry the request.

See Errors for the specific code values returned under each status.

4xx (except 429) - the request will not succeed as-is. Fix the problem described by the error type/code before retrying.
429 - you are being rate limited. Wait and retry with exponential backoff.
503 - a dependency is temporarily unavailable. Retry after a short delay.
5xx - the request may or may not have been processed. Retry with the same Idempotency-Key so the operation is not duplicated. See Idempotency.