Error object

When a request fails, Paypercut returns a structured error object describing the cause of the failure.

This object is designed to support both programmatic handling and user-facing messaging.

Example

{
  "type": "card_error",
  "code": "card_declined",
  "decline_code": "insufficient_funds",
  "advice_code": "do_not_try_again",
  "network_decline_code": "51",
  "message": "Your card has insufficient funds. Please try another card or use a different payment method.",
  "param": null,
  "trace_id": "trc_123"
}

Attributes

type

Indicates the high-level category of the error.

Common values:

• invalid_request_error
• api_error
• card_error
• authentication_error

Use this field as the primary branch for handling logic.

code

A stable programmatic identifier for the error.

Use this field to implement conditional handling in your integration.

Example:

• card_declined
• parameter_invalid

decline_code

Provides a normalized reason for card-related failures.

Example:

• insufficient_funds
• expired_card
• authentication_required

Use this field to determine how to respond to payment failures.

advice_code

Indicates how to proceed after an error.

Typical values include:

• try_again_later
• do_not_try_again
• confirm_card_data
• adjust_amount

Use this field to guide retry and user interaction strategies.

network_decline_code

The raw response code returned by the card network or issuer.

Example:

• 05
• 51
• 54

This field is primarily used for diagnostics and reporting.

network_advice_code

The raw advice code provided by the network, if available.

Use this for advanced diagnostics and operational analysis.

message

A human-readable description of the error.

For card errors, this message is safe to display to end users.

param

Indicates which request parameter caused the error, if applicable.

Example:

{
  "param": "card_number"
}

Use this field to highlight the relevant input field in your UI.

violation_code

A short identifier for rule or validation violations.

Use this field for advanced validation handling if needed.

trace_id

A unique identifier for the request.

How to use the error object

Your integration should:

• Use type and code for programmatic handling
• Use decline_code and advice_code for payment decisions
• Use message for user-facing feedback
• Use param to guide form validation
• Use trace_id for debugging and support

Related pages

• Error handling
• Error codes
• Declines