---
updatedAt: 2025-08-15T00:23:44.000Z
agentTools:
  projectIndex: https://partner.getpliant.com/llms.txt
---

# Error Handling

Pliant uses standard HTTP status codes to indicate whether an API request was successful or resulted in an error.

* `2xx` codes indicate a successful operation.
* `4xx` codes indicate client-side errors — for example, when required parameters are missing or the request is malformed.
* `5xx` codes indicate server-side errors on Pliant's infrastructure. These are usually temporary, and retries should include a backoff strategy to avoid excessive traffic.

***

## HTTP Response Codes

| Status Code | Description                                                                                                                                      |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `200`       | OK — The request was successful, and everything worked as expected.                                                                              |
| `202`       | Accepted — The request was accepted and is being processed asynchronously. A callback will be triggered once the operation completes.            |
| `204`       | No Content — The request was successful, but there's no content to return. This may indicate a disabled feature module for the requested entity. |
| `400`       | Bad Request — The request was malformed or invalid and could not be processed.                                                                   |
| `401`       | Unauthorized — The API consumer is not authenticated.                                                                                            |
| `403`       | Forbidden — The API consumer is authenticated but not allowed to access the requested resource.                                                  |
| `404`       | Not Found — The requested resource does not exist.                                                                                               |
| `409`       | Conflict — The request could not be completed due to a resource conflict (e.g., locked object).                                                  |
| `500`       | Internal Server Error — An unexpected error occurred on Pliant’s servers.                                                                        |
| `503`       | Service Unavailable — A temporary error occurred on Pliant’s servers. Retry after a short delay using an exponential backoff strategy.           |

***

## Common Error Messages

Below are examples of common business-logic-related error messages. This list is not exhaustive but is a good starting point for implementing granular error handling. All other unexpected errors should be caught by a generic handler.

| Endpoint Group | Error Code                   | Error Message                                                                                                                  |
| -------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Cardholder     | `USER_ALREADY_EXISTS`        | User with the same email already exists in organization \[$\{organizationId}].                                                 |
| Receipt        | `RECEIPT_FILE_ERROR`         | Receipt file type not supported: image/gif                                                                                     |
| Receipt        | `RECEIPT_UPLOAD_NOT_ENABLED` | `receiptUploadEnabled` set to `false` for transactionId=$\{transactionId}.                                                     |
| Card           | `ILLEGAL_ARGUMENTS_PROVIDED` | Activation code doesn't match.                                                                                                 |
| Card           | `INVALID_ACCESS_CODE`        | Invalid card access code for activation.                                                                                       |
| Card           | `ILLEGAL_STATUS_TRANSITION`  | Card in status $\{card.status} cannot be unlocked.                                                                             |
| Card           | `LOCKED_BY_CARD_CONTROL`     | Card is locked by card control and cannot be unlocked manually.                                                                |
| Card           | `NOT_ACTIVE_ORG`             | Card can only be issued for ACTIVE organizations. organizationId=$\{organizationId}, status=$\{organization.status}.           |
| Card           | `INVALID_PHONE_NUMBER`       | Phone number must start with '+' followed by 8 to 15 digits. memberId=$\{cardholderId}, phoneNumber=$\{phoneNumber}.           |
| Card           | `CARD_NAME_NOT_SUPPORTED`    | Card names are not supported for \{cardType} cards.                                                                            |
| Card           | `ILLEGAL_ARGUMENTS_PROVIDED` | Unsupported validity period. Valid periods for virtual cards: \[3, 6, 9, 12, 18, 24, 30, 36].                                  |
| Card           | `ILLEGAL_ARGUMENTS_PROVIDED` | If card control categories are used, all fields are mandatory.                                                                 |
| Card           | `ILLEGAL_ARGUMENTS_PROVIDED` | If card control merchants are used, all fields are mandatory.                                                                  |
| Card           | `ILLEGAL_ARGUMENTS_PROVIDED` | If card control dates are used, all fields are mandatory.                                                                      |
| Card           | `ILLEGAL_ARGUMENTS_PROVIDED` | If card control times are used, all fields are mandatory.                                                                      |
| Card           | `ILLEGAL_ARGUMENTS_PROVIDED` | DATE or TIME card controls can't be set while using card validity parameters.                                                  |
| Card Request   | `ISSUANCE_LIMIT_EXCEEDED`    | Issuance limit reached. Card not created. memberId=$\{memberId}, organizationId=$\{organizationId}, cardConfig=$\{cardConfig}. |
| Card Request   | `COMMENT_IS_MANDATORY`       | Comment is mandatory for SINGLE\_USE cards.                                                                                    |
| General        | `API_VERSION_NOT_SUPPORTED`  | Minimum API version is 2.1.0. Provided version is 2.0.0.                                                                       |
| General        | `ILLEGAL_ARGUMENTS_PROVIDED` | Payload is missing mandatory fields.                                                                                           |