Status reasons

When an API operation is successfully processed (HTTP 2xx response), the resource in the response body may be in a state that requires additional action or indicates a business-level failure. To help you understand and handle these situations, resources include a reason block that provides context about the current status.

Reason block structure

The reason block, when present, contains two fields:

• code: an enumeration value in lower_snake_case format that identifies the specific cause of the status. This format is designed to be machine-readable for programmatic handling while remaining human-readable.
• description: a human-friendly explanation of the reason, suitable for logging, debugging, or displaying to end users in English (it is not localized, use the code to localize yourself the error if needed).

{
  "id": "pay_47xnabxkz48h7bq0s84wj14654",
  "status": "declined",
  "reason": {
    "code": "insufficient_funds",
    "description": "The payment was declined due to insufficient funds"
  }
}

Usage guidelines

Use the code field for programmatic decision-making in your integration. The description field is intended for human consumption and may change over time, so avoid parsing or relying on its exact wording in your code logic.

Resource-specific reason codes

Each resource type has a different set of possible reason codes based on its status. For example:

• Payments may have reason codes like insufficient_funds, or stole_card for declined status while a refund operation does not return those reason codes for its declined status.
• The specific codes available depend on the resource's current status (e.g., declined, failed, action_required).

Refer to the documentation for each resource type to see the complete list of possible reason codes and their meanings.