# Errors

When an error occurs, the xMoney API will return an error response in JSON format.
The response will include a status code, a message, and an array of errors.

## Error response format

The error response will be in the following format:


```json
{
  "code": 400,
  "message": "Bad Request",
  "errors": [
    {
      "code": 1651,
      "message": "Invalid email address provided",
      "type": "Validation",
      "field": "email"
    }
  ]
}
```

The `errors` array will contain a list of errors that occurred. Each error will have the following fields:

| Field | Description |
|  --- | --- |
| `code` | The error code. |
| `message` | A human-readable message describing the error. |
| `type` | The type of error `Exception` or `Validation`. |
| `field` | The field that the error occurred in (if applicable). |


## HTTP Status Codes

These are standard HTTP status codes used to indicate the general category of the response.

| Code | Constant | Description |
|  --- | --- | --- |
| 200 | HTTP_OK | The request was successful |
| 201 | HTTP_CREATED | A new resource was successfully created |
| 202 | HTTP_ACCEPTED | The request has been accepted for processing |
| 303 | HTTP_SEE_OTHER | Redirect to another resource |
| 400 | HTTP_BAD_REQUEST | The request was invalid or cannot be processed |
| 401 | HTTP_UNAUTHORIZED | Authentication is required or has failed |
| 402 | HTTP_PAYMENT_REQUIRED | Payment is required to proceed |
| 403 | HTTP_FORBIDDEN | You don't have permission to access this resource |
| 404 | HTTP_NOT_FOUND | The requested resource was not found |
| 409 | HTTP_CONFLICT | The request conflicts with the current state of the resource |
| 500 | HTTP_SYSTEM_ERROR | An internal server error occurred |
| 502 | HTTP_BAD_GATEWAY | The server received an invalid response from an upstream server |
| 504 | HTTP_GATEWAY_TIMEOUT | The server did not receive a timely response from an upstream server |


## General Purpose Errors (6xx)

These errors relate to general API usage, authentication, and common validation issues.

| Code | Constant | Description | Field(s) |
|  --- | --- | --- | --- |
| 601 | API_KEY_INVALID | The provided API key is invalid or malformed | `apiKey` |
| 602 | PAGE_INVALID | Invalid page number for pagination (must be between 1 and 1,000,000,000) | `page` |
| 603 | PER_PAGE_INVALID | Invalid items per page value (must be between 1 and 1,000) | `perPage` |
| 604 | TAG_MISSING | The tag field is required but was not provided | `tag` |
| 605 | TAG_INVALID | The tag value is invalid (must be alphanumeric, max 100 chars) | `tag` |
| 606 | IP_INVALID | The IP address format is invalid | `ip` |
| 607 | CURRENCY_NOT_SUPPORTED | The specified currency is not supported | `currency` |
| 609 | DATABASE_ERROR | A database error occurred while processing the request | — |
| 610 | CURRENCY_MISSING | The currency field is required but was not provided | `currency` |
| 611 | CURRENCY_INVALID | The currency code is invalid (must be 3 uppercase letters) | `currency` |
| 612 | DESCRIPTION_MISSING | The description field is required but was not provided | `description` |
| 613 | DESCRIPTION_INVALID | The description is invalid (max 65,535 characters) | `description` |
| 614 | DATE_INVALID | The date format is invalid (use ISO 8601 format) | Various |
| 615 | TAG_NOT_FOUND | The specified tag was not found | `tag` |
| 616 | TAG_EXISTS | A tag with this value already exists | `tag` |
| 617 | GREATER_THEN_ID_INVALID | Invalid greaterThanId value for pagination | `greaterThanId` |
| 618 | SITE_ID_MISSING | The siteId field is required but was not provided | `siteId` |
| 619 | JSON_VALUE_MISSING | A required JSON field is missing | Various |
| 620 | JSON2_VALUE_INVALID | The JSON value is invalid or malformed | Various |
| 621 | URL_MISSING | The URL field is required but was not provided | `url` |
| 622 | URL_INVALID | The URL format is invalid (must be 10-250 characters) | `url` |
| 623 | BOOLEAN_MISSING | A required boolean field is missing | Various |
| 624 | BOOLEAN_INVALID | The boolean value is invalid (use true/false, yes/no, 1/0) | Various |
| 625 | PUBLIC_KEY_MISSING | The public key field is required but was not provided | `publicKey` |
| 626 | PUBLIC_KEY_INVALID | The public key is invalid | `publicKey` |
| 627 | SITE_ID_INVALID | The siteId format is invalid (must be numeric) | `siteId` |
| 634 | JSON_VALUE_INVALID | The JSON value is invalid or malformed | Various |
| 638 | DELETE_MESSAGE_MISSING | The deletion message is required but was not provided | `message` |
| 639 | DELETE_MESSAGE_INVALID | The deletion message is invalid (max 65,535 characters) | `message` |
| 640 | BASE64_VALUE_MISSING | A required Base64 encoded field is missing | Various |
| 641 | BASE64_VALUE_INVALID | The Base64 encoded value is invalid or malformed | Various |
| 642 | SITE_DISABLED | The specified site is disabled and cannot be used | `siteId` |


## Order Errors (7xx)

These errors relate to order creation, updates, and management.

| Code | Constant | Description | Field(s) |
|  --- | --- | --- | --- |
| 700 | ORDER_ID_MISSING | The orderId field is required but was not provided | `orderId` |
| 701 | ORDER_ID_INVALID | The orderId format is invalid (must be numeric, max 32 digits) | `orderId` |
| 702 | ORDER_TYPE_MISSING | The orderType field is required but was not provided | `orderType` |
| 703 | ORDER_TYPE_INVALID | The orderType value is invalid | `orderType` |
| 712 | FIRST_BILL_DATE_MISSING | The firstBillDate is required for recurring orders | `firstBillDate` |
| 713 | FIRST_BILL_DATE_INVALID | The firstBillDate format is invalid (use ISO 8601 format) | `firstBillDate` |
| 714 | INTERVAL_TYPE_MISSING | The intervalType is required for recurring orders | `intervalType` |
| 715 | INTERVAL_TYPE_INVALID | The intervalType is invalid (use 'day' or 'month') | `intervalType` |
| 716 | INTERVAL_VALUE_MISSING | The intervalValue is required for recurring orders | `intervalValue` |
| 717 | INTERVAL_VALUE_INVALID | The intervalValue is invalid (must be 1-365) | `intervalValue` |
| 718 | TRIAL_AMOUNT_MISSING | The trialAmount is required but was not provided | `trialAmount` |
| 719 | TRIAL_AMOUNT_INVALID | The trialAmount format is invalid | `trialAmount` |
| 720 | TRANSACTION_METHOD_ID_MISSING | The transactionMethodId is required but was not provided | `transactionMethodId` |
| 721 | TRANSACTION_METHOD_ID_INVALID | The transactionMethodId format is invalid | `transactionMethodId` |
| 722 | ORDER_UPDATE_CONFLICT | Cannot update the order due to a conflict with its current state | — |
| 723 | ORDER_INSUFFICIENT_DATA | Insufficient data provided to create or process the order | — |
| 724 | ORDER_REQUEST_BODY_INVALID | The order request body is invalid | — |
| 725 | ORDER_NOT_FOUND | The specified order was not found | `orderId` |
| 730 | ORDER_STATUS_MISSING | The orderStatus field is required but was not provided | `orderStatus` |
| 731 | ORDER_STATUS_INVALID | The orderStatus value is invalid | `orderStatus` |
| 732 | ORDER_RETRY_PAYMENT_MISSING | The retryPayment field is required but was not provided | `retryPayment` |
| 733 | ORDER_RETRY_PAYMENT_INVALID | The retryPayment format is invalid (use ISO 8601 duration format) | `retryPayment` |
| 734 | ORDER_CREATE_CONFLICT | Cannot create order due to a conflict (e.g., duplicate) | — |
| 735 | NEXT_DUE_DATE_MISSING | The nextDueDate is required but was not provided | `nextDueDate` |
| 736 | NEXT_DUE_DATE_INVALID | The nextDueDate format is invalid (use ISO 8601 format) | `nextDueDate` |
| 737 | ORDER_EXTERNAL_ORDER_ID_MISSING | The externalOrderId is required but was not provided | `externalOrderId` |
| 740 | LEVEL3_DATA_INVALID | The Level 3 transaction data is invalid | `level3Data` |
| 741 | ORDER_EXTERNAL_ORDER_ID_INVALID | The externalOrderId format is invalid (alphanumeric, max 32 chars) | `externalOrderId` |


## Transaction Errors (8xx)

These errors relate to payment transactions, including authorizations, captures, and refunds.

| Code | Constant | Description | Field(s) |
|  --- | --- | --- | --- |
| 800 | TRANSACTION_ID_MISSING | The transactionId is required but was not provided | `transactionId` |
| 801 | TRANSACTION_ID_INVALID | The transactionId format is invalid (must be numeric, max 32 digits) | `transactionId` |
| 802 | TRANSACTION_METHOD_MISSING | The transactionMethod is required but was not provided | `transactionMethod` |
| 803 | TRANSACTION_METHOD_INVALID | The transactionMethod value is invalid | `transactionMethod` |
| 804 | AMOUNT_MISSING | The amount is required but was not provided | `amount` |
| 805 | AMOUNT_INVALID | The amount format is invalid (must be positive numeric) | `amount` |
| 808 | CARD_HOLDER_NAME_MISSING | The cardHolderName is required but was not provided | `cardHolderName` |
| 809 | CARD_HOLDER_NAME_INVALID | The cardHolderName is invalid (max 250 characters) | `cardHolderName` |
| 814 | CARD_TYPE_MISSING | The cardType is required but was not provided | `cardType` |
| 815 | CARD_TYPE_INVALID | The cardType value is invalid | `cardType` |
| 816 | CARD_NUMBER_MISSING | The cardNumber is required but was not provided | `cardNumber` |
| 817 | CARD_NUMBER_INVALID | The cardNumber is invalid (invalid format, checksum, or issuer) | `cardNumber` |
| 818 | CARD_EXPIRY_DATE_MISSING | The cardExpiryDate is required but was not provided | `cardExpiryDate` |
| 819 | CARD_EXPIRY_DATE_INVALID | The cardExpiryDate is invalid (use MM/YY format) | `cardExpiryDate` |
| 820 | CARD_CVV_MISSING | The cardCvv is required but was not provided | `cardCvv` |
| 821 | CARD_CVV_INVALID | The cardCvv is invalid (must be 3-4 digits) | `cardCvv` |
| 822 | CARD_BLACKLISTED | The card has been blacklisted and cannot be used | — |
| 824 | TRANSACTION_NOT_FOUND | The specified transaction was not found | `transactionId` |
| 825 | TRANSACTION_EXISTS | A transaction with this identifier already exists | — |
| 826 | TRANSACTION_UPDATE_CONFLICT | Cannot update the transaction due to a conflict | — |
| 827 | TRANSACTION_TYPE_MISSING | The transactionType is required but was not provided | `transactionType` |
| 828 | TRANSACTION_TYPE_INVALID | The transactionType value is invalid | `transactionType` |
| 829 | TRANSACTION_STATUS_MISSING | The transactionStatus is required but was not provided | `transactionStatus` |
| 830 | TRANSACTION_STATUS_INVALID | The transactionStatus value is invalid | `transactionStatus` |
| 834 | TRANSACTION_FRAUD_SUSPECTED | The transaction was declined due to suspected fraud | — |
| 835 | TRANSACTION_INSUFFICIENT_FUNDS | The transaction was declined due to insufficient funds | — |
| 836 | TRANSACTION_DECLINED | The transaction was declined by the issuing bank | — |
| 837 | TRANSACTION_REJECTED | The transaction was rejected by the payment provider | — |
| 838 | TRANSACTION_TIMED_OUT | The transaction timed out (try again later) | — |
| 839 | TRANSACTION_SOFT_DECLINED | The transaction with saved card was soft declined by the issuing bank | — |
| 840 | TRANSACTION_PENDING | The transaction is pending (waiting for async response) | — |
| 841 | TRANSACTION_SOURCE_MISSING | The transaction source is required but was not provided | `source` |
| 842 | TRANSACTION_SOURCE_INVALID | The transaction source value is invalid | `source` |
| 843 | PROVIDER_RESPONSE_TIMEOUT | The payment provider did not respond in time | — |
| 844 | PROVIDER_RESPONSE_INVALID | The payment provider returned an invalid response | — |
| 845 | DATE_TYPE_MISSING | The dateType field is required but was not provided | `dateType` |
| 846 | DATE_TYPE_INVALID | The dateType value is invalid | `dateType` |
| 848 | EXTERNAL_CUSTOM_DATA_MISSING | The externalCustomData is required but was not provided | `externalCustomData` |
| 849 | EXTERNAL_CUSTOM_DATA_INVALID | The externalCustomData format is invalid | `externalCustomData` |
| 855 | TRANSACTION_CREDIT_INSUFFICIENT_FUNDS | The credit transaction failed due to insufficient funds | — |
| 856 | PROVIDER_RESPONSE_CODE_INVALID | The payment provider returned an invalid response code | — |
| 857 | CARD_DATA_MISSING | The card data is required but was not provided | — |
| 858 | CARD_DATA_INVALID | The card data is invalid | — |
| 859 | TRANSACTION_MODE_INVALID | The transaction mode is invalid | `transactionMode` |
| 860 | TRANSACTION_OPTION_INVALID | The transactionOption is invalid | `transactionOption` |
| 861 | TRANSACTION_OPTION_MISSING | The transactionOption is required but was not provided | `transactionOption` |
| 862 | TO_SITE_MISSING | The toSite field is required for split payments | `toSite` |
| 863 | TO_SITE_INVALID | The toSite value is invalid | `toSite` |
| 864 | PROVIDER_REQUEST_VALIDATION_ERROR | The request to the payment provider failed validation | — |
| 865 | PROVIDER_RESPONSE_VALIDATION_ERROR | The response from the payment provider failed validation | — |


## Card Errors (9xx)

These errors relate to saved cards and card management.

| Code | Constant | Description | Field(s) |
|  --- | --- | --- | --- |
| 900 | CARD_ID_MISSING | The cardId is required but was not provided | `cardId` |
| 901 | CARD_ID_INVALID | The cardId format is invalid (must be numeric, max 11 digits) | `cardId` |
| 902 | CARD_NOT_FOUND | The specified card was not found | `cardId` |
| 903 | CARD_STATUS_MISSING | The cardStatus is required but was not provided | `cardStatus` |
| 904 | CARD_STATUS_INVALID | The cardStatus value is invalid | `cardStatus` |


## Extra/Resource Errors (10xx)

These errors relate to resource management and extra services.

| Code | Constant | Description | Field(s) |
|  --- | --- | --- | --- |
| 1000 | RESOURCE_TYPE_MISSING | The resource type is required but was not provided | `resourceType` |
| 1001 | RESOURCE_TYPE_INVALID | The resource type value is invalid | `resourceType` |
| 1002 | RESOURCE_ID_MISSING | The resource ID is required but was not provided | `resourceId` |
| 1003 | RESOURCE_ID_INVALID | The resource ID format is invalid | `resourceId` |
| 1004 | UPDATES_MESSAGE_MISSING | The update message is required but was not provided | `message` |
| 1005 | UPDATES_MESSAGE_INVALID | The update message is invalid | `message` |
| 1006 | DELETE_REASON_MISSING | The deletion reason is required but was not provided | `reason` |
| 1007 | DELETE_REASON_INVALID | The deletion reason is invalid | `reason` |
| 1008 | DELETE_REASON_ID_MISSING | The deletion reason ID is required but was not provided | `reasonId` |
| 1009 | DELETE_REASON_ID_INVALID | The deletion reason ID is invalid | `reasonId` |
| 1010 | DELETE_REASON_TYPE_MISSING | The deletion reason type is required but was not provided | `reasonType` |
| 1011 | DELETE_REASON_TYPE_INVALID | The deletion reason type is invalid | `reasonType` |
| 1012 | DOWNLOAD_NOT_FOUND | The requested download was not found | — |


## Customer Errors (16xx)

These errors relate to customer data and management.

| Code | Constant | Description | Field(s) |
|  --- | --- | --- | --- |
| 1620 | CUSTOMER_ID_MISSING | The customerId is required but was not provided | `customerId` |
| 1621 | CUSTOMER_ID_INVALID | The customerId format is invalid | `customerId` |
| 1626 | CUSTOMER_NOT_FOUND | The specified customer was not found | `customerId` |
| 1627 | CUSTOMER_EXISTS | A customer with this identifier already exists | — |
| 1630 | FIRST_NAME_MISSING | The firstName is required but was not provided | `firstName` |
| 1631 | FIRST_NAME_INVALID | The firstName is invalid (max 100 characters) | `firstName` |
| 1632 | LAST_NAME_MISSING | The lastName is required but was not provided | `lastName` |
| 1633 | LAST_NAME_INVALID | The lastName is invalid (max 100 characters) | `lastName` |
| 1634 | COUNTRY_MISSING | The country is required but was not provided | `country` |
| 1635 | COUNTRY_INVALID | The country code is invalid (use ISO 3166-1 alpha-2/alpha-3) | `country` |
| 1636 | STATE_MISSING | The state is required but was not provided | `state` |
| 1637 | STATE_INVALID | The state code is invalid (use ISO 3166-2) | `state` |
| 1638 | CITY_MISSING | The city is required but was not provided | `city` |
| 1639 | CITY_INVALID | The city is invalid (max 100 characters) | `city` |
| 1640 | ZIP_MISSING | The zipCode is required but was not provided | `zipCode` |
| 1641 | ZIP_INVALID | The zipCode is invalid (alphanumeric, max 100 characters) | `zipCode` |
| 1642 | ADDRESS_MISSING | The address is required but was not provided | `address` |
| 1643 | ADDRESS_INVALID | The address is invalid (max 150 characters) | `address` |
| 1644 | PHONE_MISSING | The phone is required but was not provided | `phone` |
| 1645 | PHONE_INVALID | The phone is invalid (max 16 digits, optional + prefix) | `phone` |
| 1646 | EMAIL_MISSING | The email is required but was not provided | `email` |
| 1647 | EMAIL_INVALID | The email address is invalid | `email` |
| 1648 | CUSTOMER_UPDATE_CONFLICT | Cannot update the customer due to a conflict | — |
| 1649 | CUSTOMER_DELETE_CONFLICT | Cannot delete the customer due to existing dependencies | — |


## Limit Exceeded Errors (18xx)

These errors indicate that a transaction or volume limit has been exceeded.

| Code | Constant | Description |
|  --- | --- | --- |
| 1800 | LIMIT_EXCEEDED_SITE_MONTHLY_VOLUME | The site's monthly transaction volume limit has been exceeded |
| 1801 | LIMIT_EXCEEDED_SITE_DAILY_VOLUME | The site's daily transaction volume limit has been exceeded |
| 1802 | LIMIT_EXCEEDED_SITE_TRANSACTION_VOLUME | The site's transaction amount limit has been exceeded |
| 1803 | LIMIT_EXCEEDED_SITE_DAILY_TRANSACTION_NUMBER | The site's daily transaction count limit has been exceeded |
| 1804 | LIMIT_EXCEEDED_CUSTOMER_DAILY_VOLUME | The customer's daily transaction volume limit has been exceeded |
| 1805 | LIMIT_EXCEEDED_CUSTOMER_DAILY_TRANSACTION_NUMBER | The customer's daily transaction count limit has been exceeded |


### Digital Wallet Errors (228x)

These errors relate to digital wallets (e.g., Google Pay, Apple Pay).

| Code | Constant | Description | Field(s) |
|  --- | --- | --- | --- |
| 2280 | DIGITAL_WALLET_TYPE_NOT_SUPPORTED | The digital wallet type is not supported | `type` |
| 2281 | DIGITAL_WALLET_ERROR_ON_DECRYPT | An error occurred while decrypting the digital wallet data | — |
| 2282 | DIGITAL_WALLET_CANNOT_DECRYPT_DATA | Unable to decrypt the digital wallet data | — |
| 2283 | DIGITAL_WALLET_DATA_INVALID | The digital wallet data is invalid | — |
| 2284 | DIGITAL_WALLET_MISSING_PARAM | A required digital wallet parameter is missing | — |


## Other Errors (9xxx)

| Code | Constant | Description | Field(s) |
|  --- | --- | --- | --- |
| 9001 | FUNDS_CONFIRMATION_ERROR | An error occurred while confirming funds availability | — |


## Example Error Responses

### 400 Bad Request - Validation Error


```json
{
  "code": 400,
  "message": "Bad Request",
  "errors": [
    {
      "code": 804,
      "message": "*amount* is a required field",
      "type": "Validation",
      "field": "amount"
    }
  ]
}
```

### 404 Not Found


```json
{
  "code": 404,
  "message": "Not Found",
  "errors": [
    {
      "code": 902,
      "message": "Card not found",
      "type": "Exception"
    }
  ]
}
```

### 409 Conflict


```json
{
  "code": 409,
  "message": "Conflict",
  "errors": [
    {
      "code": 1627,
      "message": "Customer already exists",
      "type": "Exception"
    }
  ]
}
```

### Transaction Declined


```json
{
  "code": 400,
  "message": "Bad Request",
  "errors": [
    {
      "code": 836,
      "message": "Transaction declined by issuing bank",
      "type": "Exception"
    }
  ]
}
```

## Best Practices for Error Handling

1. **Always check the HTTP status code first** to understand the general category of the response.
2. **Iterate through the errors array** to handle multiple validation errors in a single request.
3. **Use the error code** for programmatic handling rather than parsing the message string.
4. **Log the full error response** for debugging purposes.
5. **Display user-friendly messages** based on the error code rather than showing raw API messages to end users.
6. **Handle common errors gracefully**:
  - `401 Unauthorized`: Refresh authentication or re-authenticate
  - `404 Not Found`: Verify the resource ID is correct
  - `409 Conflict`: Check for duplicate resources or state conflicts
  - `422/400 Validation errors`: Display field-specific error messages
7. **Implement retry logic** for transient errors like `504 Gateway Timeout` or `838 Transaction Timed Out`.