Errors

When a request fails, the API answers with an HTTP status code and a JSON body. Use the status to decide what to do and error_code, when there is one, to tell causes apart.

Status codes

Name
2xx
Description
The request worked. 201 means something was created. 202 on a payment confirmation means the card network has not given a final answer yet (see Payment sessions).
Name
4xx
Description
The request was refused. Fix the request; repeating it unchanged gives the same answer. 429 means too many requests: wait for the time in the Retry-After header.
Name
5xx
Description
Something went wrong on our side. The body only says Internal server error. Routes that take an Idempotency-Key (charges and refunds) can be retried safely with the same key.

The error body

Every error has a human-readable message. Many have an error_code that stays the same when the wording changes. Check the code, not the text.

401 with invalid_credentials covers a missing, wrong, revoked or wrong-kind key alike, so the response does not tell an attacker which part was wrong.

A few codes you may meet:

Name
invalid_credentials
Description
401. The key or session is not valid.
Name
forbidden_key_type
Description
403. A publishable key was used on a route that needs a secret key.
Name
kyb_required, kyb_pending, kyb_rejected, email_not_verified
Description
403. A live-mode request from an account that has not finished verification.
Name
amount_too_small, amount_too_large
Description
400. The amount is outside what the currency allows.
Name
payment_processing
Description
202. The payment is not settled yet.

Error response

{
  "message": "Amount must be at least 50 (minor units) for usd",
  "error_code": "amount_too_small"
}