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 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).
CodeDescriptionReason
400Bad RequestThe request was unacceptable, often due to missing a required parameter.
401UnauthorisedNo valid API key provided.
402Request FailedThe parameters were valid but the request failed.
403ForbiddenThe API key doesn’t have permissions to perform the request.
404Not FoundThe requested resources doesn’t exist.
409ConflictThe request conflicts with another request (perhaps due to using the same idempotent key).
422Unprocessable ContentThe parameters were valid but the request could not be processed.
429Too Many RequestsToo many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500Internal Server ErrorsA generic error occurred on our side.
502, 503, 504Gateway/Timeout ErrorsIssues communicating with external dependencies or internal services.

​
Problem Details

When an error occurs, we return a JSON response conforming to RFC 9457. For example, a typical error response might look like this: 
{
  "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 field of the response. This object is included in payment related responses and has the following structure: 
{
  "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.
  • 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.
  • 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 CodeDescription
account_invalidThe 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_limitThe payment cannot be completed with the provided amount, please try again with a different amount.
card_declinedThe payment could not be completed with this card. Please check decline_code for more details.
insufficient_fundsThe card does not have enough funds.

​
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 CodeDescriptionRectification Action
account_closedThe cardholder’s account has been closed.Use a different payment method.
additional_customer_authentication_requiredThe card was declined because the transaction requires authentication.The customer should try again and authenticate their card when prompted during the transaction.
blocked_first_useThe transaction was blocked by the issuer.The customer needs to contact their card issuer to resolve the issue.
cannot_verify_pinThe transaction requires PIN but it couldn’t be verified.The customer needs to try again by inserting their card and entering a PIN.
card_expiredThe card has expired.The customer needs to use a valid, non-expired card.
card_not_foundThe card was not found in the records of the issuer.The customer needs to contact their card issuer to resolve the issue.
customer_canceledThe customer has canceled the transaction or recurring payment.Confirm the customer’s intent or request a different payment method.
cvv_not_validThe customer entered an incorrect CVV code.The customer needs to re-enter the correct CVV code.
do_not_honorThe card issuer has declined the transaction without a specific reason.The customer needs to contact their card issuer for more information.
generic_declineThe card issuer declined the transaction for an unspecified reason.The customer needs to contact their card issuer or try a different card.
geo_restrictedThe transaction was declined due to geographic restrictions by the issuer.The customer needs to contact their issuer or use a different payment method.
incorrect_pinThe PIN entered is incorrect.The customer needs to try again with the correct PIN.
insufficient_fundsThe card has insufficient funds to complete the transaction.The customer needs to add funds or use a different card.
invalid_account_typeThe card, or account the card is connected to is invalid.The customer needs to contact their card issuer to resolve the issue.
invalid_amountThe 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_numberThe card number is incorrect.The customer needs to try again using the correct card number.
invalid_merchantThe merchant was not recognized by the payment processor.Reach out to the payment processor to resolve the issue.
invalid_transactionThe transaction was rejected by the issuer.The merchant needs to contact the payment processor to resolve the issue.
issuer_temporarily_unavailableThe 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_unavailableThe 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_exceededThe transaction exceeds the card’s credit or withdrawal limit.The customer needs to use a different card or wait until the limit resets.
lost_cardThe card has been reported as lost.Use an alternate payment method.
no_action_takenThe transaction was attempted but no action was taken.The customer should retry the transaction.
no_reasonThe card was declined for an unknown reason.The customer needs to contact their card issuer to resolve the issue.
partial_approvalThe transaction could not be fully completed as authorized.The customer needs to contact their issuer or use a different payment method.
pickup_cardThe 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_requiredThe card was declined because it requires a PIN.The customer needs to try again by inserting their card and entering a PIN.
pin_retries_exceededThe allowable number of PIN tries was exceeded.The customer must use another card or method of payment.
recurring_charge_stopped_by_customerYour customer asked their bank to deny charges from your account.Stop the recurring payments immediately.
refer_to_issuerThe card issuer declined the transaction for an unspecified reason.The customer needs to contact their issuer or use a different payment method.
retry_transactionThe 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_violationThe card was declined for an unknown reason.The customer needs to contact their issuer or use a different payment method.
stolen_cardThe card has been reported as stolen.Use an alternate payment method.
suspected_fraudThe transaction was flagged as suspicious by the issuer.The customer needs to contact their card issuer to resolve the issue.
system_errorA temporary error occurred during the transaction.Wait a minute or two and try again.
transaction_failed_aml_checkThe 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_permittedThe payment is not permitted.The customer needs to contact their card issuer to resolve the issue.
unable_to_route_transactionThe 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_issuerThe card issuer is not recognized or doesn’t exist.The customer needs to contact their issuer or use a different payment method.
unsolicited_reversalA 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.