Error Handling

PaveWay uses standard HTTP response codes to indicate the success or failure of an API request. 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, a charge failed, etc.).
Codes in the 5xx range indicate an error with PaveWay’s servers.

internal Error Object

When an error occurs, the response body will contain a standardized error object.

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "The 'amount' field must be a positive integer.",
    "param": "amount",
    "request_id": "req_abc123"
  }
}

Attributes

type

string

required

The type of error returned. Can be one of: api_error, card_error, idempotency_error, or invalid_request_error.

code

string

For some errors that could be handled programmatically, a short string indicating the error code reported.

message

string

required

A human-readable message providing more details about the error. For card errors, these messages can be shown to your users.

param

string

If the error is parameter-specific, the parameter related to the error. For example, for a card error, this could be card_number.

request_id

string

The ID of the request that generated the error. Helpful for debugging and support.

Error Types

Type	Description
`api_error`	Unexpected internal server error. Retry the request.
`card_error`	Card errors are the most common type of error when processing payments. They occur when the user’s card issuer declines a charge, or if the card is improperly authenticated.
`idempotency_error`	Occurs when an `Idempotency-Key` is reused for a different request payload. keys must be unique.
`invalid_request_error`	Occurs when a request has invalid parameters.
`authentication_error`	Occurs when authentication fails (missing or invalid API key).
`rate_limit_error`	Occurs if you make too many requests too quickly.

Common Error Codes

Payment & Card Errors

Code	Description
`card_declined`	The card has been declined.
`insufficient_funds`	The card has insufficient funds to complete the purchase.
`expired_card`	The card has expired.
`incorrect_cvc`	The CVC code is incorrect.
`processing_error`	An error occurred while processing the card.
`provider_error`	The upstream payment provider is experiencing issues.

Validation Errors

Code	Description
`parameter_invalid`	One or more parameters are invalid. Check the `param` field or `details` array (for validation errors).
`parameter_missing`	A required parameter is missing.
`resource_not_found`	The requested resource ID (e.g., customer, payment intent) does not exist.
`resource_already_exists`	You are trying to create a resource that already exists (e.g., duplicate customer email).

Idempotency Errors

Code	Description
`idempotency_key_in_use`	The idempotency key has already been used for a different request.

Introduction

Payment Collection

Subscriptions

Advanced

internal Error Object

Attributes

Error Types

Common Error Codes

Payment & Card Errors

Validation Errors

Idempotency Errors

​internal Error Object

​Attributes

​Error Types

​Common Error Codes

​Payment & Card Errors

​Validation Errors

​Idempotency Errors

internal Error Object

Attributes

Error Types

Common Error Codes

Payment & Card Errors

Validation Errors

Idempotency Errors