> ## Documentation Index > Fetch the complete documentation index at: https://docs.momentco.io/llms.txt > Use this file to discover all available pages before exploring further. # Errors > Learn how the API handles errors This guide outlines how our API handles errors, providing consistent, structured information to developers to help them diagnose and respond to failures effectively. ## HTTP Error codes We follow industry standards for HTTP status codes and enrich them with detailed error information using the [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457.html) Problem Details for HTTP APIs specification. ### Standard Status Codes In general, codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, etc.). Codes in the 5xx range indicate an error with our servers (these are rare). | Code | Description | Reason | | ------------- | ---------------------- | ------------------------------------------------------------------------------------------------ | | 400 | Bad Request | The request was unacceptable, often due to missing a required parameter. | | 401 | Unauthorised | No valid API key provided. | | 402 | Request Failed | The parameters were valid but the request failed. | | 403 | Forbidden | The API key doesn’t have permissions to perform the request. | | 404 | Not Found | The requested resources doesn't exist. | | 409 | Conflict | The request conflicts with another request (perhaps due to using the same idempotent key). | | 422 | Unprocessable Content | The parameters were valid but the request could not be processed. | | 429 | Too Many Requests | Too many requests hit the API too quickly. We recommend an exponential backoff of your requests. | | 500 | Internal Server Errors | A generic error occurred on our side. | | 502, 503, 504 | Gateway/Timeout Errors | Issues communicating with external dependencies or internal services. | ### Problem Details When an error occurs, we return a JSON response conforming to [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457.html). For example, a typical error response might look like this: ```json theme={"system"} { "type": "https://api.momentco.io/docs/errors#not-found", "title": "The requested resource was not found", "status": 404, "detail": "The requested resources doesn't exist", "instance": "/collect/payment_sessions/ps_36dED4m12MLxn48BUrn4R" } ``` This standard ensures that each error response includes a consistent set of fields, such as: * `type`: A URI identifier for the error type. * `title`: A short, human-readable summary of the problem. * `status`: The HTTP status code. * `detail`: A human-readable explanation specific to the occurrence. * `instance`: A unique identifier for the error occurrence (can be used in support/debugging). These fields help developers quickly understand the nature of the error and how to resolve it. ## Application Error Codes In addition to HTTP status codes, we provide application-level error codes for granular insight into what went wrong during a payment operation. ### Error Object When a payment attempt fails, the failure is recorded in the [last\_payment\_error](/api-reference/collect/payment_sessions/object#schema-last-payment-error) field of the response. This object is included in payment related responses and has the following structure: ```json theme={"system"} { "error_code": "card_declined", "decline_code": "insufficient_funds", "message": "The card has insufficient funds.", "timestamp": "2025-06-03T12:34:56Z" } ``` The fields are: * `error_code`: A general error code indicating the high-level reason for failure, (e.g. `card_declined`). See [Error Codes](/api-reference/getting-started/errors#error-codes). * `decline_code`: A more specific code that explains why a card transaction was declined, typically provided by the issuing bank, payment processor, or credit card network. (e.g. `insufficient_funds`). See [Decline Codes](/api-reference/getting-started/errors#decline-codes). * `message`: A human-readable message describing the error. * `timestamp`: An ISO 8601 timestamp indicating when the error occurred. ### Error Codes A general error code indicating the high-level reason for failure. The following are the possible values for the `code` field, along with their descriptions: | Error Code | Description | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `account_invalid` | The request tried to create a payment, but the account number was invalid. The request was rejected. Corrective action: Advise the customer to check the account number. | | `amount_beyond_limit` | The payment cannot be completed with the provided amount, please try again with a different amount. | | `card_declined` | The payment could not be completed with this card. Please check decline\_code for more details. | | `insufficient_funds` | The card does not have enough funds. | ### Mandate Error Codes When processing payment sessions, mandates enable recurring or series-based payments. A mandate is created during a `first_in_series` payment by passing a `mandate_options` block, which defines the consent taken from the customer. This mandate is then associated with the customer's payment method and enforced on subsequent `next_in_series` payments. If a mandate validation fails during a `next_in_series` payment, the API returns a synchronous error response in the standard RFC 9457 format: ```json theme={"system"} { "title": "Mandate Amount Out of Range", "status": 400, "code": "mandate_amount_out_of_range", "detail": "The payment amount falls outside the range allowed by the mandate", "instance": "/collect/payment_sessions" } ``` The following mandate error codes may be returned: | Error Code | Description | | ------------------------------------------- | ----------------------------------------------------------------------- | | `mandate_not_found` | The specified mandate could not be found. | | `invalid_mandate_status` | The mandate is not in a valid status for this operation. | | `mandate_expired` | The mandate has expired and can no longer be used. | | `mandate_not_yet_started` | The mandate has not yet reached its start date. | | `mandate_max_payments_reached` | The maximum number of payments allowed by the mandate has been reached. | | `mandate_already_used` | The mandate has already been used and cannot be reused. | | `mandate_amount_out_of_range` | The payment amount falls outside the range allowed by the mandate. | | `mandate_amount_exceeds_limit` | The payment amount exceeds the limit set by the mandate. | | `payment_not_eligible_for_mandate_creation` | The payment is not eligible for creating a mandate. | ### Decline Codes A more specific code that explains why a card transaction was declined, typically provided by the issuing bank, payment processor, or credit card network. The following are the possible values for the `decline_code` field, along with their descriptions and recommended rectification actions: | Decline Code | Description | Rectification Action | | --------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `account_closed` | The cardholder’s account has been closed. | Use a different payment method. | | `additional_customer_authentication_required` | The card was declined because the transaction requires authentication. | The customer should try again and authenticate their card when prompted during the transaction. | | `blocked_first_use` | The transaction was blocked by the issuer. | The customer needs to contact their card issuer to resolve the issue. | | `cannot_verify_pin` | The transaction requires PIN but it couldn't be verified. | The customer needs to try again by inserting their card and entering a PIN. | | `card_expired` | The card has expired. | The customer needs to use a valid, non-expired card. | | `card_not_found` | The card was not found in the records of the issuer. | The customer needs to contact their card issuer to resolve the issue. | | `customer_canceled` | The customer has canceled the transaction or recurring payment. | Confirm the customer’s intent or request a different payment method. | | `cvv_not_valid` | The customer entered an incorrect CVV code. | The customer needs to re-enter the correct CVV code. | | `do_not_honor` | The card issuer has declined the transaction without a specific reason. | The customer needs to contact their card issuer for more information. | | `generic_decline` | The card issuer declined the transaction for an unspecified reason. | The customer needs to contact their card issuer or try a different card. | | `geo_restricted` | The transaction was declined due to geographic restrictions by the issuer. | The customer needs to contact their issuer or use a different payment method. | | `incorrect_pin` | The PIN entered is incorrect. | The customer needs to try again with the correct PIN. | | `insufficient_funds` | The card has insufficient funds to complete the transaction. | The customer needs to add funds or use a different card. | | `invalid_account_type` | The card, or account the card is connected to is invalid. | The customer needs to contact their card issuer to resolve the issue. | | `invalid_amount` | The payment amount is invalid, or exceeds the amount that's allowed. | If the amount appears to be correct, the customer needs to check with the issuer that they can make purchases of that amount. | | `invalid_card_number` | The card number is incorrect. | The customer needs to try again using the correct card number. | | `invalid_merchant` | The merchant was not recognized by the payment processor. | Reach out to the payment processor to resolve the issue. | | `invalid_transaction` | The transaction was rejected by the issuer. | The merchant needs to contact the payment processor to resolve the issue. | | `issuer_temporarily_unavailable` | The card issuer couldn't be reached, so the payment couldn't be authorized. | Attempt the payment again. If you still can't process it, the customer needs to contact the issuer. | | `issuer_unavailable` | The card issuer couldn't be reached, so the payment couldn't be authorized. | The customer needs to contact their card issuer to resolve the issue. | | `limit_exceeded` | The transaction exceeds the card’s credit or withdrawal limit. | The customer needs to use a different card or wait until the limit resets. | | `lost_card` | The card has been reported as lost. | Use an alternate payment method. | | `no_action_taken` | The transaction was attempted but no action was taken. | The customer should retry the transaction. | | `no_reason` | The card was declined for an unknown reason. | The customer needs to contact their card issuer to resolve the issue. | | `partial_approval` | The transaction could not be fully completed as authorized. | The customer needs to contact their issuer or use a different payment method. | | `pickup_card` | The customer can’t use this card to make this payment (it’s possible it was reported lost or stolen). | The customer needs to contact their issuer or use a different payment method. | | `pin_data_required` | The card was declined because it requires a PIN. | The customer needs to try again by inserting their card and entering a PIN. | | `pin_retries_exceeded` | The allowable number of PIN tries was exceeded. | The customer must use another card or method of payment. | | `recurring_charge_stopped_by_customer` | Your customer asked their bank to deny charges from your account. | Stop the recurring payments immediately. | | `refer_to_issuer` | The card issuer declined the transaction for an unspecified reason. | The customer needs to contact their issuer or use a different payment method. | | `retry_transaction` | The payment couldn't be processed by the issuer for an unknown reason. | The payment needs to be attempted again. If it still can't be processed, the customer needs to contact their card issuer. | | `security_violation` | The card was declined for an unknown reason. | The customer needs to contact their issuer or use a different payment method. | | `stolen_card` | The card has been reported as stolen. | Use an alternate payment method. | | `suspected_fraud` | The transaction was flagged as suspicious by the issuer. | The customer needs to contact their card issuer to resolve the issue. | | `system_error` | A temporary error occurred during the transaction. | Wait a minute or two and try again. | | `transaction_failed_aml_check` | The transaction was flagged for suspicion of money laundering by the issuer. | The customer needs to contact their card issuer to resolve the issue. | | `transaction_not_permitted` | The payment is not permitted. | The customer needs to contact their card issuer to resolve the issue. | | `unable_to_route_transaction` | The payment could not be routed to the issuer due to network or system errors on the issuers side. | The transaction can be retried, the customer needs to contact the issuer to resolve the issue if the issue persists | | `unknown_issuer` | The card issuer is not recognized or doesn't exist. | The customer needs to contact their issuer or use a different payment method. | | `unsolicited_reversal` | A reversal was initiated without a prior request or authorization from the merchant. | The merchant needs to contact the customer to resolve the issue. | ## Best Practices for Clients To ensure reliable and developer-friendly integrations, we recommend the following practices when handling errors from our API: * Always check the HTTP status code before attempting to parse the response body. Use it to determine the broad category of error (e.g., client-side vs. server-side). * Use the `error_code` field for internal application logic. This field is stable and maps to general error categories (e.g., card\_declined). It’s ideal for branching error-handling flows or conditional retry logic. * Use the `message` field for human-readable error messages that can be logged or displayed in dashboards. This message is designed to be developer-friendly but not always end-user appropriate. * Use the `decline_code` field for additional context, especially for card-related failures. These codes represent issuer-specific reasons for declines and are useful for analytics, support tooling, or to tailor customer-facing messages when applicable. * Log the full `last_payment_error` object on failed payment attempts for easier debugging and operational visibility. * Retry only when appropriate: * Retry on `5xx` errors with backoff. * Do not retry on `4xx` errors unless explicitly documented as safe to do so (e.g. when rate limited). * Monitor for `402 - Request Failed` errors to detect cases where the request has been accepted but the state of the object may indicate a processing error, for example a payment has been created, but the payment processing may still have failed. * Monitor for `422 - Unprocessable Content` errors to detect integration issues, such as invalid payment state or business rule violations.