Payve uses HTTP status codes and a JSON error body. Read the status first, then error.code.

Error format

string
A stable, machine-readable code. Branch on this.
string
A sentence for a person. The wording can change. Do not match on it.
string
Identifies this request. Log it and quote it to support. Not present on every error.
object
Extra facts for some codes, such as the fields that failed validation.

Validation errors

A request body that fails validation returns 422 with the failing fields:
An unknown field in the body is also a validation error.

The short format

Some responses come straight from the web framework and have no error.code. Authentication failures, an unknown URL and a malformed id in a URL look like this:
Write one error handler that copes with both formats: if error is an object, use error.code; if error is a string, use the HTTP status and the top-level message.

HTTP statuses

Error codes

The Status column shows the HTTP status where the code always arrives with the same one.

Validation

validation_missing_field is also the code on a few 400 responses that have no more specific code. Read the message and details.code.

Idempotency

Wallets

Quotes

Resources

Channels

A channel is the bank or operator connection that carries a payment.

Authentication and permission

Compliance and limits

Rate limiting and server errors

Payouts that fail later

A payout can be accepted with 202 and fail afterwards, for example when the recipient’s bank rejects it. That is not an HTTP error. You learn of it from the payout.failed webhook or from GET /v1/payouts/{id}, where userMessage gives the reason in plain words.

Cautions

Never retry a money call with a new idempotency key because you got an error you did not understand. Look up the transaction first. A 500 or a timeout does not prove nothing happened.
Log error.code, error.requestId, the HTTP status and your Idempotency-Key for every failed call, and quote them when you contact support.