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.