Errors

The API uses HTTP status codes to show whether a request worked. Codes in the 2xx range mean success, 4xx means something about the request needs fixing, and 5xx means something went wrong on our side.

Error body

Error responses have this JSON body:

JSON

{
  "messages": ["See errors"],
  "error_code": "VALIDATION_ERROR",
  "errors": ["amount must be greater than 0"]
}

Field	Description
messages	An array of human-readable messages. They're for logs and debugging; don't match on their text.
error_code	A stable code to branch on in your code.
errors	Only on validation errors: the list of problems with the request.

For payment failures (declined cards and so on), see Failure messages.

Status codes

Status	error_code	When it happens	What to do
400	PARAMETER_MISSING	A required parameter or the request body is missing.	Fix the request.
403	UNAUTHORIZED	The API key is missing or invalid, or the endpoint isn't enabled for your account.	Check the Authorization: Bearer <key> header and that you're using the right key for the environment (sandbox or production).
403	ACCOUNT_BLOCKED	Your account is blocked.	Check your dashboard or contact support.
403	FEATURE_NOT_ENABLED	The feature, for example international payouts, isn't enabled for your account.	Contact support.
404	RECORD_NOT_FOUND	No record with that identifier exists on your account.	Check the identifier.
422	VALIDATION_ERROR	The request failed validation. Details are in errors.	Fix the fields listed in errors.
422	RECORD_NOT_UNIQUE	Two requests with the same Idempotency-Key arrived at the same time. (Sending a key again later returns the original result instead of an error.)	Retry with the same key to get the original result.
422	UNPROCESSABLE_ENTITY	The request is valid but can't be carried out, for example refunding a disputed payment.	Read messages; retrying the same request won't help.
422	INSUFFICIENT_BALANCE	Your balance doesn't cover the payout.	Top up your balance, then retry.
429	—	You went over the rate limit. This response has no JSON body.	Wait, then retry with backoff.
5xx	—	Something went wrong on our side.	Retry GET requests with backoff. Before retrying a request that creates something, check whether it was created. If it keeps happening, contact support with the request details.

📘

An invalid or missing API key returns 403, not 401.