Ansa API endpoints indicate failures or problems through (1) HTTP status codes and (2) error objects in the JSON response body.

HTTP status codes

Status Code	Status	Description
`200`	OK	Everything worked as expected.
`201`	Created	The operation successfully created a resource.
`204`	No Content	This response code is specifically assigned to a pre-flight `OPTIONS` request
`400`	Bad Request	The request was malformed, often due to missing a required parameter or invalid data in the request.
`401`	Unauthorized	No valid API key provided.
`402`	Payment Failed	The parameters were valid but the request has failed. Applicable to payment endpoints such as `add balance`.
`403`	Forbidden	The API key doesn't have permissions to perform the request.
`409`	Conflict	The request conflicts with another request, often due to using the same idempotency key.
`429`	Too Many Requests (Ratelimiting)	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
`500`, `502`, `503`, `504`	Ansa Internal Error	Something went wrong with Ansa's end.

Error attributes

Field	Type	Description
`type`	`string`	Error category. Possible values are: `api_error`: Catch all. Can cover any other type of problem (e.g. transient Ansa issue). `payment_method_error`: Error derived from processing the payment method. `insufficient_funds`: Error indicating that the customer attempted to spend more funds than were available. `invalid_request_error`: Error indicating invalid parameters or arguments. `risk_error`: Error associated with high risk/fraud profile.
`code`	`string`	A short enum string indicating the specific error code reported. See the list of error codes for more details.
`message`	`string`	A human-readable message providing more details about the error.
`declineCode`	`string`	For card errors resulting from a card issuer or payment processor decline, a short string indicating the reason for the decline. See the list of decline codes for more details.
`deficit`	`object`	The deficit object provides information when a transaction fails due to insufficient funds. This happens when the customer's balance or payment method cannot cover the full amount required for the transaction. Attributes are: amount `integer`: The difference between the required amount (purchase amount) and the amount available (customer balance). currency `currency`: The transaction currency.

Error codes

The following error codes may be returned in an Error object.

Error Code	Description
`request_failed`	Indicates the request failed with valid parameters. This may indicate a decline from the payment service provider.
`internal`	A code for Ansa internal errors.
`invalid_customer_id`	Invalid id or no such customer exists.
`invalid_merchant_id`	Invalid id or no such merchant exists.
`duplicate_merchant`	Conflict due to an existing merchant.
`invalid_merchant_name`	Invalid merchant name.
`missing_parameter`	Required parameter is missing.
`unsupported_payment_method`	The provided payment method is not supported.
`invalid_parameter`	The provided parameter is invalid.
`invalid_body`	The provided request body is invalid.
`invalid_email`	Invalid email.
`invalid_phone`	Invalid phone number.
`invalid_payment_method_token`	Invalid payment method token.
`invalid_amount`	Invalid transaction amount.
`invalid_currency_code`	Invalid currency code.
`insufficient_funds`	Attempted to spend more funds than were available.
`high_risk`	The transaction was rejected due to a high risk profile.
`unsupported_functionality`	Requested functionality is not supported.

Decline codes

The following decline codes may be returned in an Error object as the declineCode field.

These decline codes map to errors returned by the Payment Service Provider (PSP.

📘
Improve payment conversion rates
In order to improve payment conversion rates, it is crucial to display a helpful message to users when they enter payment information. To assist you with this, Ansa has provided a table below with user-friendly messages that you can display to guide users in correctly entering their payment information.

🚧
Never return the decline code directly to the user, especially for fraudulent declines.

Decline Code	User Friendly Message
`GENERIC_DECLINE`	We are unable to process your payment information. Please re-enter your payment details and try again.
`INSUFFICIENT_FUNDS`	Your account does not have sufficient funds for this transaction. Please try again with a different payment method.
`FRAUDULENT_CHARGE`	We are unable to process your payment information. Please re-enter your payment details and try again.
`INVALID_ACCOUNT`	We are unable to process your payment information. Please re-enter your payment details and try again.
`INVALID_CVC`	We are unable to process your payment information. Please re-enter your payment details and try again.
`EXPIRED_CARD`	The card you entered has expired. Please re-enter the payment details or try with a different payment method.
`INVALID_EXPIRY_DATE`	The card you entered has expired. Please re-enter the payment details or try with a different payment method.
`INVALID_NUMBER`	We are unable to process your payment information. Please re-enter your payment details and try again.
`INCORRECT_AVS`	The address or zip code entered does not match the card billing details on file. Please re-enter the address and try again.
`INVALID_AMOUNT`	We are unable to process your payment information. Please try again.
`INVALID_REFUND`	We are unable to process your payment information. Please try again.
`DUPLICATE_TRANSACTION`	We are unable to process your payment information. Please try again.
`MERCHANT_ERROR`	We are unable to process your payment information. Please try again.