Network Tokenization API Error Handling

If the Network Tokenization API fails, you’ll receive an error in the format of the following example:

{
  "errorDetails": {
    "reason": "CardNotEligible",
    "message": "This card cannot be used for tokenization at this moment."
  }
}

Some errors include a 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"
      }
    ]
  }
}

Why Tokenization Can Fail

The API Error Details table below outlines each error code and the recommended next action you should take after receiving it. Keep in mind as you review these recommendations: a tokenization request can be rejected by the card network or the issuing bank, and the response doesn’t necessarily tell you why. Networks and issuers exclude the specifics to prevent bad actors from learning what tripped a card. As a result, an error like IssuerDeclined can cover several causes, including a fraud lock, a lost or stolen card, or a card the issuer can’t verify. If the card network sends more detail, we pass it in the message field.

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. CVV2 is optional on every network, so leaving it out won’t cause a decline on its own, but if you send it, it must be correct; an incorrect value triggers an error.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:

Endpoint	HTTP Response Codes
/tokenize	201, 400, 401, 409, 500
/transact	200, 400, 401, 404, 500
/status	200, 400, 401, 404, 409, 500
/account	200, 400, 401, 404, 500
/resume	200, 400, 401, 404, 500
/suspend	200, 400, 401, 404, 500
/delete	200, 400, 401, 404, 500

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; limit to a couple retries to avoid the issuer declining your request under concerns of a carding attack. Use Real-Time Account Updater to request an updated expiration date.
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. This error can mean invalid expiration date if the card brand is Visa. Consider including CVV2 and billing address if not already provided, or use Real-Time Account Updater to request updated details. Limit to a couple retries to avoid the issuer declining your request under concerns of a carding attack.
400	`InvalidParameter`	`Your request does not have valid set of parameters required to process the business function.`	If the network sent an explanation, it’ll appear in the `message` field. Otherwise, correct the PAN and expiry, then retry the request. Consider including CVV2 and billing address.
400	`IssuerDeclined`	`Declined by Issuer.`	Do not retry; if the network sent an explanation, it’ll appear in the `message` field. This error can mean invalid expiration date if the card brand is Mastercard.
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, starting with a one-second wait
400	`NoResponseFromIssuer`	`No response from issuer.`	Temporary network or infrastructure issue; wait and retry with exponential backoff, starting with a one-second wait
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, starting with a one-second wait
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, starting with a one-second wait
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.

Authentication

Data & Response Codes

Data Ingestion

BIN Database

Account Updater