Integration guides
Errors
The error format, every error code and how to handle each one.
Errors use one envelope and a stable code. Show your own message to customers; log request_id
and quote it when you contact support.
{
"error": {
"code": "idempotency_conflict",
"message": "This idempotency key was already used for a different request.",
"request_id": "6f1c0a2b9d3e4f51"
}
}| HTTP | code | Meaning | What to do |
|---|---|---|---|
| 401 | invalid_credential | Missing, invalid, revoked, expired or wrong-environment key. | Check the key and environment. |
| 403 | scope_denied | The key does not have this endpoint's scope. | Create a key with the scope. |
| 403 | access_denied | Your account cannot use this feature now (not approved, suspended or not verified). | Check capabilities; contact support. |
| 403 | developer_access_denied | Developer access is not enabled for this account. | Contact support. |
| 404 | not_found | The resource does not exist for your account. | Check the ID. |
| 405 | method_not_allowed | Wrong HTTP method for this path. | See the API reference. |
| 409 | idempotency_conflict | The key was used with a different body (or a payout quote expired). | Use a new key for a new operation. |
| 422 | invalid_request | A field, header or query parameter is invalid or unknown. | Fix the request. |
| 422 | collection_limit_exceeded | Above your available transaction or daily limit. | Lower the amount or wait. |
| 422 | invalid_amount | Outside your account's or the market's allowed amounts. | Use an allowed amount. |
| 422 | unsupported_market | customer.country and money.currency are not enabled for your key. | Check supported_countries in capabilities. |
| 422 | unsupported_currency | Currency not enabled for your account. | Use an enabled currency. |
| 422 | payment_profile_unavailable | The payment_profile_id does not exist on your account. | Check the profile ID. |
| 422 | unsupported_api_version | The TeePay-Version header is not supported. | Use 2026-10-18. |
| 429 | rate_limited | Too many requests or a quota is reached. | Wait for Retry-After. |
| 500 | internal_error | Unexpected error. | Retry with the same idempotency key; contact support with request_id. |
| 503 | unavailable, admission_unavailable | A dependency is temporarily unavailable. | Retry after Retry-After with the same key. |
An error is not a payment outcome
A 5xx or a timeout on a create request does not mean the payment failed. Retry with the same
idempotency key or read the resource before telling the customer anything.