Errors

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.

​

HTTP Error codes

​

Standard Status Codes

​

Problem Details

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

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

​

Application Error Codes

​

Error Object

{
  "error_code": "card_declined",
  "decline_code": "insufficient_funds",
  "message": "The card has insufficient funds.",
  "timestamp": "2025-06-03T12:34:56Z"
}

• 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

​

Mandate Error Codes

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

​

Decline Codes

​

Best Practices for Clients

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