{
"errorDetails": {
"reason": "CardNotEligible",
"message": "This card cannot be used for tokenization at this moment."
}
}
details array containing field-level information, including a location (the camelCase property name that caused the error) and a message describing the issue. This information doesn’t contain PAN or cardholder data and is safe to surface to end users.
For example, a ValidationFailed error always includes details:
{
"errorDetails": {
"reason": "ValidationFailed",
"message": "Missing or invalid fields.",
"details": [
{
"location": "expirationDate.Year",
"message": "'Expiration Date Year' must be greater than 0"
}
]
}
}
Improve your tokenization success rateIncluding the card’s CVV2 value and billing address (at minimum, postal code) in your
/tokenize request can reduce CardVerificationFailed and InvalidParameter failures. Some card issuers require this additional data to approve token provisioning. See the /tokenize endpoint documentation for field details.HTTP Response Codes
What endpoint you call determines the types of HTTP response codes you can potentially receive. This table outlines the types of errors you can receive:API Error Details
| HTTP Response Code | errorDetails reason | errorDetails message | Retry/Recommended Action |
|---|---|---|---|
| 400 | InvalidProperty | A property validation check has failed. | Correct the input, then retry the request |
| 400 | InvalidInput | The tokenization service could not find data linked with provided input. | Check your Token Reference Id or Asset UUID, then retry with corrected input; if you can’t identify an issue, contact your Pagos Account Manager |
| 400 | InvalidRequest | The tokenization service could not validate the request. | Review the error JSON object for more details, then retry with corrected input |
| 400 | UnavailableMerchantAccount | The merchant account is not available. | Contact your Pagos Account Manager |
| 400 | CardEligibilityError | The card is not eligible for network tokenization. | Do not retry |
| 400 | InvalidPanReferenceFormat | The PAN reference format is invalid. | Contact your Pagos Account Manager |
| 400 | InvalidPanReference | The requested PAN could not be found. | Contact your Pagos Account Manager |
| 400 | InvalidTokenReferenceFormat | The token reference format is invalid. | Correct the input, then retry the request |
| 400 | InvalidMerchantStatus | The merchant account is in an invalid status for the requested operation. | Contact your Pagos Account Manager |
| 400 | NoActiveTokens | There are no active (not suspended) Tokens for the given Account PAN and consumer account. | Do not retry as is; re-tokenize the PAN |
| 400 | InvalidAssetReference | The requested asset could not be found. | Correct the input, then retry the request |
| 400 | InvalidUuidFormat | The Uuid format is invalid. | Correct the input, then retry the request |
| 400 | InvalidPanFormat | The PAN format is invalid, or other data associated with the PAN was incorrect or entered incorrectly. | Correct the input, then retry the request |
| 400 | InvalidPan | The PAN is invalid. | Correct the input, then retry the request |
| 400 | InvalidTrid | The TRID is invalid. | Contact your Pagos Account Manager |
| 400 | InvalidTridNetwork | The TRID network is invalid. | Contact your Pagos Account Manager |
| 400 | InvalidPanNetwork | The PAN network is invalid. | Contact your Pagos Account Manager |
| 400 | InvalidPanExpiryFormat | The PAN expiry format is invalid. | Correct the input, then retry the request |
| 400 | InvalidPanExpiry | The PAN expiry is invalid. | Correct the input, then retry the request |
| 400 | InvalidTokenStatus | The current token’s status doesn’t support the requested operation. | Do not retry as is; call /status to get Token’s current status |
| 400 | ProvisionDataExpired | The PAN information provided is considered stale. | Correct the input, then retry the request |
| 400 | CardVerificationFailed | Invalid payment instrument or data associated with the payment instrument. | Do not retry as is; consider including CVV2 and billing address if not already provided |
| 400 | InvalidParameter | Your request does not have valid set of parameters required to process the business function. | Correct the PAN and expiry, then retry the requst; consider including CVV2 and billing address |
| 400 | IssuerDeclined | Declined by Issuer. | Do not retry |
| 400 | MerchantNotFound | Can’t find the merchant with specified ID. | Contact your Pagos Account Manager |
| 400 | NetworkRateLimit | The network rate limit is exceeded. | Temporary network or infrastructure issue; wait and retry with exponential backoff |
| 400 | NoResponseFromIssuer | No response from issuer. | Temporary network or infrastructure issue; wait and retry with exponential backoff |
| 400 | OperationNotSupported | Operation not supported. | Contact your Pagos Account Manager |
| 400 | TridConflict | Cannot perform operation for this card for this merchant. | Contact your Pagos Account Manager |
| 400 | AsyncTaskNotReady | This task is not ready yet. | Temporary network or infrastructure issue; wait and retry with exponential backoff |
| 400 | ValidationFailed | Missing or invalid fields. | Correct the input, then retry the request |
| 400 | CardNotEligible | This card cannot be used for tokenization at this moment. | Do not retry |
| 400 | CardNotAllowed | The requested action is not allowed for a given PAN. | Do not retry |
| 400 | CardDeclined | This card is considered not eligible for tokenization at this time. | Do not retry |
| 400 | CardExpired | Card expired. | Do not retry |
| 400 | CardCancelled | Card is cancelled. | Do not retry |
| 400 | CardMarketNotSupported | The market of the Card provided is not supported. | Do not retry |
| 400 | CardCannotBeTokenized | The Card is ineligible for tokenization due to an ongoing issue such as fraud. | Do not retry |
| 400 | UnauthorizedOperation | The Token Reference ID cannot have its status changed as the token has been deleted. | Do not retry |
| 400 | IssuerNotSupported | The Issuer of the Card provided does not support provisioning for cards they issue. | Do not retry |
| 400 | ProvisionNotAllowed | Further operations for this card are no longer allowed. | Do not retry |
| 400 | UserLockedOutFromProvisioning | User is locked out from provisioning. | Contact your Pagos Account Manager |
| 409 | DuplicateRequest | The PAN has already been provisioned to the device or the same request is currently being processed. | Do not retry |
| 401 | AuthenticationFailed | The tokenization service could not authenticate the request. | Correct the input, then retry the request |
| 404 | InvalidTokenReference | The requested token could not be found. | Correct the input, then retry the request; contact your Pagos Account Manager if the problem persists |
| 404 | MetadataNotAvailable | The requested token’s metadata is not available. | Correct the Token Reference ID, then retry the request |
| 404 | AccountNotFound | Account not found. | Contact your Pagos Account Manager |
| 404 | AsyncTaskNotFound | Async task not found. | Correct the Task ID, then retry the request |
| 404 | BatchJobNotFound | Batch job was not found. | Correct the Batch job ID, then retry the request |
| 400 | SystemError | A system error occurred. | Contact your Pagos Account Manager |
| 400 | NetworkError | The network cannot process the request. | Temporary network or infrastructure issue; wait and retry with exponential backoff |
| 500 | InternalServerError | Contact Pagos, include the requestId with communications. | An unexpected internal error occurred; re-submit your request later and contact your Pagos Account Manager with the requestId from the response body if the problem persists |
Every error response includes a
requestId field in the response body. When contacting Pagos support about any error (not just 500s), include this value to help us quickly locate the relevant logs. If you send an X-TRACE-ID header with your request, it will be used as the requestId in the response.