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": "CardEligibilityError",
    "message": "This card is not eligible for network tokenization."
  }
}

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, 429, 500, 503
/transact	200, 401, 404, 429, 500, 503
/status	200, 401, 404, 429, 500, 503
/account	200, 401, 404, 429, 500, 503
/resume	200, 400, 401, 404, 429, 500, 503
/suspend	200, 400, 401, 404, 429, 500, 503
/delete	200, 400, 401, 404, 429, 500, 503

API Error Details

HTTP Response Code	`errorDetails` reason	`errorDetails` message	Recommended Action
400	`InvalidProperty`	`A property validation check has failed.`	Re-submit your request after correcting the input
400	`InvalidInput`	`The tokenization service could not find data linked with provided input.`	Check your Token Reference Id or Asset UUID; 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
400	`UnavailableMerchantAccount`	`The merchant account is not available.`	Contact your Pagos account manager
400	`CardEligibilityError`	`The card is not eligible for network tokenization.`	No further action required
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.`	Re-submit your request after correcting the input
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.`	Re-tokenize the PAN
400	`InvalidAssetReference`	`The requested asset could not be found.`	Re-submit your request after correcting the input
400	`InvalidUuidFormat`	`The Uuid format is invalid.`	Re-submit your request after correcting the input
400	`InvalidPanFormat`	`The PAN format is invalid, or other data associated with the PAN was incorrect or entered incorrectly.`	Re-submit your request after correcting the input
400	`InvalidPan`	`The PAN is invalid.`	Re-submit your request after correcting the input
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.`	Re-submit your request after correcting the input
400	`InvalidPanExpiry`	`The PAN expiry is invalid.`	Re-submit your request after correcting the input
400	`InvalidTokenStatus`	`The current token's status doesn't support the requested operation.`	Call /status to get Token’s current status
400	`ProvisionDataExpired`	`The PAN information provided is considered stale.`	No further action required
400	`CardVerificationFailed`	`Invalid payment instrument or data associated with the payment instrument.`	No further action required
400	`CardNotEligible`	`This card cannot be used for tokenization at this moment.`	No further action required
400	`CardNotAllowed`	`The requested action is not allowed for a given PAN.`	No further action required
400	`CardDeclined`	`This card is considered not eligible for tokenization at this time.`	No further action required
400	`CardExpired`	`Card expired.`	No further action required
400	`CardCancelled`	`Card is cancelled.`	No further action required
400	`CardMarketNotSupported`	`The market of the Card provided is not supported.`	No further action required
400	`CardCannotBeTokenized`	`The Card is ineligible for tokenization due to an ongoing issue such as fraud.`	No further action required
400	`UnauthorizedOperation`	`The Token Reference ID cannot have its status changed as the token has been deleted.`	No further action required
400	`IssuerNotSupported`	`The Issuer of the Card provided does not support provisioning for cards they issue.`	No further action required
400	`ProvisionNotAllowed`	`Further operations for this card are no longer allowed.`	No further action required
400	`UserLockedOutFromProvisioning`	`User is locked out from provisioning.`	Contact your Pagos account manager
400	`DuplicateRequest`	`The PAN has already been provisioned to the device or the same request is currently being processed.`	No further action required
401	`AuthenticationFailed`	`The tokenization service could not authenticate the request.`	Re-submit your request with correct credentials
404	`InvalidTokenReference`	`The requested token could not be found.`	Contact your Pagos account manager if the problem persists
404	`MetadataNotAvailable`	`The requested token's metadata is not available.`	Re-submit your request with a valid Token Reference ID
404	`AccountNotFound`	`Account not found.`	Contact your Pagos account manager
404	`BatchJobNotFound`	`Batch job was not found.`	Re-submit your request with a valid Batch job ID
429	`concurrentLimitExceeded`	`You exceeded the maximum allowed concurrent API calls.`	Keep concurrent API calls within the allowed Concurrent API Request Limits
500	`SystemError`	`A system error occurred.`	Contact your Pagos account manager
503	`NetworkError`	`The network cannot process the request.`	Re-submit your request later; contact Pagos if the problem persists

Authentication

Data & Response Codes

Data Ingestion

Pagos MCP Server

BIN Database

Account Updater

Network Tokenization

Network Tokenization API Error Handling

HTTP Response Codes

API Error Details

​HTTP Response Codes

​API Error Details

HTTP Response Codes

API Error Details