> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pagos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Network Tokenization API Error Handling

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

```json theme={null}
{
  "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`:

```json theme={null}
{
  "errorDetails": {
    "reason": "ValidationFailed",
    "message": "Missing or invalid fields.",
    "details": [
      {
        "location": "expirationDate.Year",
        "message": "'Expiration Date Year' must be greater than 0"
      }
    ]
  }
}
```

<Tip>
  **Improve your tokenization success rate**

  Including 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](/network-tokenization/endpoint/tokenize) for field details.
</Tip>

## 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](network-tokenization/endpoint/tokenize) | 201, 400, 401, 409, 500 |
| [/transact](network-tokenization/endpoint/transact) | 200, 400, 401, 404, 500 |
| [/status](network-tokenization/endpoint/status) | 200, 400, 401, 404, 409, 500 |
| [/account](network-tokenization/endpoint/account) | 200, 400, 401, 404, 500 |
| [/resume](network-tokenization/endpoint/resumes) | 200, 400, 401, 404, 500 |
| [/suspend](network-tokenization/endpoint/suspends) | 200, 400, 401, 404, 500 |
| [/delete](network-tokenization/endpoint/deletes) | 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 |
| 400 | `InvalidTokenStatus` | `The current token’s status doesn’t support the requested operation.` | Do not retry as is; call [/status](network-tokenization/endpoint/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 |

<Note>
  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.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.