Error Reference
Every failure from the /partner/v1 and /widget/v1 APIs uses one envelope:
{
"code": "VALIDATION",
"message": "The request failed validation.",
"fieldErrors": { "customerId": "must not be blank" }
}
fieldErrors appears only on validation failures. message is always a safe sentence; use code for logic. Behaviour is separate from the widget's customer-facing messages, listed further below.
Partner API Errors
| Status | code | When | What to do |
|---|---|---|---|
400 | BAD_REQUEST | Malformed JSON, an unknown field, or a request that cannot be processed. | Fix the request; this API rejects unknown fields. |
401 | UNAUTHORIZED | Missing, malformed, unknown or revoked API key. | Check the Authorization: ApiKey ... header and the environment. |
403 | FORBIDDEN | The API key does not have the required scope. | Ask Pagamio to grant the scope. |
404 | SESSION_NOT_FOUND | Revoking a session that does not exist or is not yours. | Check the session id. |
404 | TRANSACTION_NOT_FOUND | Unknown transaction id, or one belonging to another partner. | Check the id. |
422 | VALIDATION | A field failed validation (see fieldErrors), a transaction query has neither customerId nor walletId, an unknown status, or an invalid statement date. | Fix the named fields. |
429 | RATE_LIMITED | Over your per-key request limit. | Wait for the Retry-After header (seconds), then retry with backoff. |
500 | INTERNAL_ERROR | Unexpected fault. | Retry with backoff; contact Pagamio if it persists. |
502 | UPSTREAM_UNAVAILABLE | A dependency behind Pagamio is unreachable. | Retry with backoff. |
Widget Session Errors
These reach the widget itself, not your backend, but explain what customers see.
| Status | code | Customer sees | Cause |
|---|---|---|---|
401 | SESSION_EXPIRED | "Your session has expired" | Session missing, revoked or timed out. Open a new session. |
409 | PURCHASE_IN_FLIGHT | Handled by the widget; not expected in normal use. | A second purchase was started while one was still pending. |
| Redirect | none | "This link is no longer valid" | The launch token or the widget link was rejected. |
Customer-Facing Failure Messages
When a purchase fails, the widget shows one fixed message per failureCode. Text from your wallet API is never shown.
failureCode | Message |
|---|---|
INSUFFICIENT_FUNDS | Insufficient funds in your wallet. |
CUSTOMER_NOT_FOUND | We couldn't find a wallet for your account. Please contact our support. |
WALLET_BLOCKED | Your wallet is not active. Please contact our support. |
LIMIT_EXCEEDED | This purchase is over your wallet's limit. |
VALIDATION | The purchase details were not accepted. |
PRODUCT_UNAVAILABLE | This product is temporarily unavailable. |
AGGREGATOR_DECLINED | The purchase was declined by the provider. |
TIMEOUT | We could not confirm the purchase. Please check your history later. |
UNKNOWN | Something went wrong. Please try again. |
Wallet Reason To Failure Code
Your wallet returns (422 reason) | failureCode |
|---|---|
INSUFFICIENT_FUNDS | INSUFFICIENT_FUNDS |
CUSTOMER_NOT_FOUND | CUSTOMER_NOT_FOUND |
WALLET_BLOCKED | WALLET_BLOCKED |
LIMIT_EXCEEDED | LIMIT_EXCEEDED |
VALIDATION | VALIDATION |
| Hold timed out or unconfirmed | TIMEOUT |
AUTHENTICATION, DUPLICATE, or anything else | UNKNOWN |
See Partner Wallet Contract for the full response mapping.
Last updated: September 2026