Errors
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

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:

{
  "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

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

404 Not Found

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

409 Conflict

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

Transaction Declined

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

Best Practices for Error Handling

Always check the HTTP status code first to understand the general category of the response.
Iterate through the errors array to handle multiple validation errors in a single request.
Use the error code for programmatic handling rather than parsing the message string.
Log the full error response for debugging purposes.
Display user-friendly messages based on the error code rather than showing raw API messages to end users.
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
Implement retry logic for transient errors like 504 Gateway Timeout or 838 Transaction Timed Out.

ErrorsCopyCopy for LLMCopy page as Markdown for LLMsView as MarkdownOpen this page as MarkdownOpen in ChatGPTGet insights from ChatGPTOpen in ClaudeGet insights from Claude