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 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. 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.

Business unit errors

If your API key is linked to more than one business unit, every request must identify the target business unit with the Moment-Business-Unit header. A key linked to a single business unit can omit the header.

{
  "type": "https://api.momentco.io/docs/errors#business-unit-missing",
  "title": "Missing business unit",
  "status": 400,
  "code": "business_unit_missing",
  "detail": "This API key is linked to multiple business units. Provide the Moment-Business-Unit header to select one.",
  "instance": "/collect/payment_sessions"
}

Error Code	Status	Description
`business_unit_missing`	400	The header was not sent and the API key is linked to more than one business unit.
`business_unit_invalid`	400	The header value is not a valid business unit identifier. Identifiers are prefixed with `bu_`.
`business_unit_access_denied`	403	The header value is a valid identifier, but the API key is not linked to that business unit.

A 403 business_unit_access_denied does not mean the API key is invalid. The key authenticated successfully, so rotating it does not help. Check that the business unit is one the key is entitled to use.

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 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:

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

Getting Started

Collect

Stored Value

Billing

Webhooks

Changelog

HTTP Error codes

Standard Status Codes

Problem Details

Business unit errors

Application Error Codes

Error Object

Error Codes

Mandate Error Codes

Decline Codes

Best Practices for Clients

​HTTP Error codes

​Standard Status Codes

​Problem Details

​Business unit errors

​Application Error Codes

​Error Object

​Error Codes

​Mandate Error Codes

​Decline Codes

​Best Practices for Clients

HTTP Error codes

Standard Status Codes

Problem Details

Business unit errors

Application Error Codes

Error Object

Error Codes

Mandate Error Codes

Decline Codes

Best Practices for Clients