How to read an error
Every failed request answers with a JSON envelope carrying an errorCode and a human-readable message:
{
"errorCode": 63001,
"errorMsgs": ["No card exists with the given identifier."]
}Branch on errorCode, not on the HTTP status. The status is auxiliary: the same code can arrive with different statuses depending on which operation produced it, while the code itself is stable. Each operation's possible statuses are declared in the OpenAPI specification.
The negative codes and the 13xxx / 19xxx families documented under Error Codes belong to the Payments API and are unaffected by this catalogue.
The Retry column marks the codes where repeating the same request unchanged can succeed. Everything else needs the request, the card, or the account to change first — repeating such a request will fail the same way.
HTTP statuses
| Status | What it means |
|---|---|
400 | The request, the card, or the account does not allow the operation. Read errorCode for the reason |
401 | Credentials are missing or invalid |
403 | The credentials are not permitted to perform this operation |
404 | The addressed card or resource does not exist |
409 | Not returned by any operation 1 |
422 | The operation could not be processed |
500 | An unexpected fault on our side |
502 | A service the Cards API depends on refused the operation |
503 | The service is temporarily unavailable — the same request can be retried |
Error codes
Cross-cutting
| Code | Name | Description | Retry |
|---|---|---|---|
| 62001 | InvalidRequest | The request is not valid. Check the reported fields and try again. | No |
| 62002 | IdempotencyKeyMissing | This operation requires an idempotency key. | No |
| 62003 | IdempotencyKeyConflict | This idempotency key was already used for a different request. | No |
| 62004 | ClientIntegrationSettingsMissing | This account is not configured for this operation. Contact support. | No |
| 62005 | ParentAccountLinkMissing | The specified cardholder is not linked to your account. | No |
| 62006 | UserNotApproved | The cardholder has not completed onboarding. | No |
| 62007 | UserStateIncorrect | The cardholder is not in a state that allows this operation. | No |
| 62008 | MobilePhoneMissing | The cardholder has no mobile phone number on file. | No |
| 62009 | MobilePhoneNotVerified | The cardholder's mobile phone number is not verified. | No |
| 62010 | OperationRestricted | This operation is not permitted for this account. | No |
| 62011 | ServiceTemporarilyUnavailable | The service is temporarily unavailable. Please retry in a few moments. | Yes |
| 62012 | OperationDeclined | The operation was declined. | No |
| 62013 | OperationFailed | The operation could not be completed. Contact support if it keeps happening. | No |
Card lifecycle
| Code | Name | Description | Retry |
|---|---|---|---|
| 63001 | CardNotFound | No card exists with the given identifier. | No |
| 63002 | CardNotOwnedByCaller | The card exists but was not issued by this account. | No |
| 63003 | CardStateIncorrect | The card is not in a state that allows this operation. | No |
| 63004 | CardRequestStateIncorrect | A previous request for this card is still being processed. | Yes |
| 63005 | CardBlockedByIssuer | The card is blocked by the issuer. | No |
| 63006 | CardCountLimitReached | This account has reached its limit on the number of cards. | No |
| 63007 | CardHolderNameInvalid | The cardholder name cannot be embossed. Use Latin letters only. | No |
| 63008 2 | CardPinTooWeak | The PIN is too easy to guess. Choose a different one. | No |
| 63009 | CardProgramNotFound | No card program exists with the given identifier. | No |
| 63010 | CardProgramNotResolved | No card program is available for the requested card parameters. | No |
| 63011 | PromoCardNotFound | No promo card exists with the given number. | No |
| 63012 | PromoCardAlreadyActivated | The promo card is already activated. | No |
| 63013 | PromoCardActivationRestricted | The promo card cannot be activated for this account. | No |
| 63014 | PromoCardProgramMismatch | The promo card does not match the requested card parameters. | No |
| 63015 | DeliveryOptionNotFound | The requested delivery option is not available. | No |
| 63016 | DeliveryCountryNotFound | The requested delivery country is not supported. | No |
| 63017 | CardIssuerRejected | The card issuer rejected the operation. | No |
| 63018 2 | CardDesignNotAvailable | The requested card design is not available for this card program. | No |
Which errors each area can return
Use this to narrow down what to handle where. A code that is not listed for an area is not produced there today.
| Area | Operations | Codes |
|---|---|---|
| Account | GET /v1/corporate-cards/account | 62001, 62011, 62012, 62013 |
| Card issuance | POST /v1/corporate-cards | 62001–62013, 63006, 63007, 63009, 63010, 63017 |
| Reading cards | GET /v1/corporate-cards, GET /v1/corporate-cards/{cardId} | 63001, 63002 |
| Card management | PATCH /v1/corporate-cards/{cardId}, DELETE /v1/corporate-cards/{cardId}, PATCH /v1/corporate-cards/{cardId}/frozen | 62001, 62011, 62012, 62013, 63001–63005, 63017 |
| PIN | PATCH /v1/corporate-cards/{cardId}/pin | 62001, 62004, 62011, 62012, 62013, 63001–63005, 63008, 63017 |
| Physical card reissue | POST /v1/corporate-cards/{cardId}/physical | 62001, 62011, 62012, 62013, 63001–63005, 63010, 63015, 63016, 63017 |
| Promo cards | POST /v1/corporate-cards/promo/bind | 62001, 62005–62013, 63011–63014 |
| Tokenization | GET /v1/corporate-cards/users/USERID/cards/{cardIdentity}/meawallet-tokenization-info | 62001, 62005, 62011, 62012, 62013, 63001, 63002 |
| 3DS confirmation | POST /v1/corporate-cards/3Ds/{threeDsSessionId}/confirm | 62001, 62011, 62012, 62013, 63001, 63003–63005, 63017 |
| Clearing reports | GET /v1/corporate-cards/clearing | 62001, 62011, 62012, 62013 |
| Webhook testing | POST /v1/corporate-cards/webhooks/card-test, .../transaction-test, .../authorization-test | 62004, 62013 |
Notes
- Earlier documentation described
409as the answer to a duplicate request. A duplicate idempotency key now answers400with62003. 63008and63018are published so the numbers stay stable, but no operation answers with them yet. A PIN the issuer considers too easy and an unavailable card design both answer62001today.