The API uses HTTP status codes to tell you whether a request succeeded. A code from 200 to
299 means success. Any other code means the request failed, and the body explains why.

The error body

Most error responses have a JSON body with a message:

{
  "message": "Resource not found"
}

When the request contains invalid data, the body also has an errors object. Each key is the
name of a field that failed, and each value is a list of messages for that field. All invalid
fields are reported at once:

{
  "message": "Validation failed",
  "errors": {
    "amount": ["property \"amount\" is missing"],
    "order_id": ["order_id has already been used"]
  }
}

A field inside an object is named with dots, for example order.billing_address.zipcode.

🚧
Do not depend on the exact wording
Use the status code and the field names in errors to handle an error in your code. The
text of message and of each error is meant for people and can change.

Status codes

Code	Meaning	Common causes
`400`	Bad Request	A query or path parameter is invalid, the `pensopay-version` header names an unknown version, or the payment is busy with another request.
`401`	Unauthorized	The `Authorization` header is missing, or the token is invalid or revoked.
`404`	Not Found	The resource does not exist, or it belongs to another account.
`422`	Unprocessable Entity	The request body is invalid (see `errors`), or the action was rejected, for example when a capture or refund is declined.
`429`	Too Many Requests	Your account or the payment has sent too many requests. See Rate limits.
`500`	Internal Server Error	Something went wrong on our side. Try again later, and contact support if it keeps happening.

Retrying requests

400, 401, 404, and 422 with errors: sending the same request again gives the
same result. Correct the request first. The one exception is a 400 because the payment is
busy, which you can retry after a moment.
422 when a capture, refund or cancel is rejected: the outcome can change, for example
if the acquirer had a temporary problem. Get the payment first to see its current state and
amounts, and only then decide whether to try again.
429: wait the number of seconds in the Retry-After header, then send the request
again.
500 and network errors: you can retry. Before you retry a request that creates
something, such as a payment, check whether the first request succeeded. A payment's
order_id must be unique, so a repeated create with the same order_id is rejected with
422 instead of creating a second payment.

Rate limits

Limit	Applies to
100 requests per second	All requests from one account, across all its tokens.
1000 requests per hour	Update, capture, refund, cancel and anonymize requests for a single payment.

Every request counts, whether it succeeds or not. Getting a payment does not count towards
the limit for that payment.

A request over a limit is rejected with 429 and is not carried out. The Retry-After
header holds the number of seconds until requests are accepted again:

HTTP/1.1 429 Too Many Requests
Retry-After: 1