Errors

Every 4xx and 5xx response from the Payouts API carries a structured error body so you can handle failures programmatically. For the HTTP status codes themselves, see Status Codes.

Error response shape

Every error response - for any 4xx or 5xx - has the same JSON body: a single error object.

{
  "error": {
    "type": "invalid_request_error",
    "code": "VALIDATION_ERROR",
    "message": "One or more request fields failed validation.",
    "details": {
      "amount": "must be greater than 0"
    }
  }
}

Field	Type	Description
`type`	string	Coarse, machine-readable error category. Branch on this to handle a whole class of failures without enumerating every `code`.
`code`	string	Specific, machine-readable error code. Use this when you need to react to a particular failure.
`message`	string	Human-readable description of what went wrong. Intended for logs and debugging - do not parse it.
`details`	object	Optional. Additional context, such as field-level validation failures. Present only when there is extra context to convey.

Build your error handling against type and code, never against message. Messages are meant for humans and may change at any time; the type and code values are stable contracts.

Error types

type groups every error into one of the following categories. It maps directly to the HTTP status class, so you can branch on either.

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

Error codes

The full set of code values, grouped by type.

`invalid_request_error` - `400`

`code`	Description
`VALIDATION_ERROR`	One or more request fields failed validation. See `details` for field-level context.
`INVALID_ACCOUNT_TYPE`	The account type is not supported for this operation.
`INVALID_DELIVERY_PREFERENCE`	The requested delivery preference is not valid for this delivery method.
`MCC_REQUIRED`	A merchant category code (MCC) is required for this payment.
`GOODS_RECEIVED_REQUIRED`	Confirmation that goods/services were received is required for this payment.
`IDEMPOTENCY_KEY_REQUIRED`	The `Idempotency-Key` header is required for this request.
`FEE_CALCULATION_FAILED`	Fees could not be calculated for the supplied request.

`authentication_error` - `401`

`code`	Description
`UNAUTHORIZED`	Missing or invalid credentials.

`authorization_error` - `403`

`code`	Description
`BUSINESS_NOT_ELIGIBLE`	The business is restricted (by a risk/compliance limitation) from performing this operation.

`not_found_error` - `404`

`code`	Description
`NOT_FOUND`	The requested resource does not exist.

`conflict_error` - `409`

`code`	Description
`NO_ACTIVE_API_KEY`	The partner has no active API key to bind the webhook registration to.
`DUPLICATE_ENTITY`	An entity with these identifiers already exists.
`DUPLICATE_ACCOUNT`	An account with these identifiers already exists.
`DUPLICATE_PAYMENT`	A payment with these identifiers already exists.
`DUPLICATE_EXTERNAL_ID`	The supplied `externalId` is already in use.
`ACCOUNT_IN_USE`	The account is still referenced by other resources and cannot be modified or removed.
`PAYMENT_NOT_EDITABLE`	The payment can no longer be modified in its current state.
`PAYMENT_NOT_CANCELABLE`	The payment has begun processing and can no longer be canceled.
`IDEMPOTENCY_KEY_REUSED`	The `Idempotency-Key` was reused with a different request body.
`IDEMPOTENCY_KEY_IN_PROGRESS`	Another request with this `Idempotency-Key` is still being processed.

`service_unavailable_error` - `503`

`code`	Description
`IDEMPOTENCY_STORE_UNAVAILABLE`	The idempotency store is temporarily unavailable; retry the request.

`internal_error` - `500`

`code`	Description
`INTERNAL_ERROR`	An unexpected error occurred.

For any 5xx response the message is always the generic "An unexpected error occurred" and the code is always INTERNAL_ERROR, regardless of the underlying cause - internal details are never echoed back to the caller. Rely on the HTTP status class to detect server-side failures, and contact support with your request context if they persist.

Idempotency

Write operations accept an Idempotency-Key request header. Sending the same key again returns the original result instead of performing the operation twice, which makes it safe to retry after a network error or a 5xx.

Reusing a key with a different request body returns 409 conflict_error / IDEMPOTENCY_KEY_REUSED.
Retrying while the first request is still in flight returns 409 conflict_error / IDEMPOTENCY_KEY_IN_PROGRESS - wait and retry.
If the idempotency store is temporarily down, you’ll get 503 service_unavailable_error / IDEMPOTENCY_STORE_UNAVAILABLE - retry the request.

Get started

Core resources

Building with the API

Risk, compliance & going live

Tools

Error response shape

Error types

Error codes

`invalid_request_error` - `400`

`authentication_error` - `401`

`authorization_error` - `403`

`not_found_error` - `404`

`conflict_error` - `409`

`service_unavailable_error` - `503`

`internal_error` - `500`

Idempotency

​Error response shape

​Error types

​Error codes

​invalid_request_error - 400

​authentication_error - 401

​authorization_error - 403

​not_found_error - 404

​conflict_error - 409

​service_unavailable_error - 503

​internal_error - 500

​Idempotency

Error response shape

Error types

Error codes

`invalid_request_error` - `400`

`authentication_error` - `401`

`authorization_error` - `403`

`not_found_error` - `404`

`conflict_error` - `409`

`service_unavailable_error` - `503`

`internal_error` - `500`

Idempotency