Problem responses
A problem response tells you what to repair.
The public API returns application/problem+json when it refuses a request. Read the HTTP status and code together, keep the request_id for support, and show any field errors next to the right input. A network failure may have no problem body at all.
| Response | What it means | Request handling |
|---|---|---|
| 400 · 422 | The request was refused as sent. A 400 carries field errors or a code such as invalid_request or invalid_amount; a 422 such as api_client_policy_amount_exceeded is a limit you set on this API client. From the token endpoint, a 400 invalid_scope means the token asked for a scope this API client was not given. Nothing was created or charged. | Show each field error next to its input and keep the correct values. Review the request again; never change an amount silently or split an order to pass a limit. For invalid_scope, ask for fewer scopes or create a client that has them. |
| 401 | invalid_token: the access token was missing, invalid, or expired. It does not mean a payment failed. api_client_expired means no new token can be issued. | Get a new access token from POST /oauth/token, then repeat the same request with its original idempotency key (retry: after_new_token). For api_client_expired, stop and create a new API client. |
| 403 | capability_not_granted, scope_missing, or api_client_policy_operation_not_allowed: this client or account does not have the access. Nothing was created or charged. | Explain the missing access and stop. Retrying will not help until the scope or capability is granted. |
| 404 | resource_missing: the object does not exist, or it belongs to another account or environment. | Check the ID, environment, and account. Do not treat it as a failed payment. |
| 409 | idempotency_key_reused means the payload changed under the same key. idempotency_request_in_progress means the original request is still running. A status conflict, such as attempt_in_flight, means the payment moved on. | Wait for the original request, or read the payment again and decide. Never resubmit blindly. |
| 410 | An export has expired, or its one-use download link was already used or has expired. | Request a new download session, or run the export again if the export itself expired. |
| 429 | rate_limited: the request was refused before it ran. payer_prompt_limit_reached: the payer already has too many payment prompts waiting, so nothing was sent to their phone. | Wait for Retry-After, then retry with the same Idempotency-Key and body. Check the payments already waiting on the payer's phone before starting another. |
| 500 · 503 | The outcome is unknown. A service failure is not a decline. | Read the original payment, or retry the same request with its key where the endpoint allows it. If it stays unknown, contact support with the request_id. |
Do not decide from the status code alone.
The operation and problem code tell you whether the request was definitely refused or its outcome is still unknown. Check the API reference and the unknown-outcome guide before you retry.
Every public problem code, with what to do next, is in the Problem catalog.
Machines read the same at /problems.json.