Skip to main content
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

TypeDescription
api_errorUnexpected internal server error. Retry the request.
card_errorCard 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_errorOccurs when an Idempotency-Key is reused for a different request payload. keys must be unique.
invalid_request_errorOccurs when a request has invalid parameters.
authentication_errorOccurs when authentication fails (missing or invalid API key).
rate_limit_errorOccurs if you make too many requests too quickly.

​
Common Error Codes

​
Payment & Card Errors

CodeDescription
card_declinedThe card has been declined.
insufficient_fundsThe card has insufficient funds to complete the purchase.
expired_cardThe card has expired.
incorrect_cvcThe CVC code is incorrect.
processing_errorAn error occurred while processing the card.
provider_errorThe upstream payment provider is experiencing issues.

​
Validation Errors

CodeDescription
parameter_invalidOne or more parameters are invalid. Check the param field or details array (for validation errors).
parameter_missingA required parameter is missing.
resource_not_foundThe requested resource ID (e.g., customer, payment intent) does not exist.
resource_already_existsYou are trying to create a resource that already exists (e.g., duplicate customer email).

​
Idempotency Errors

CodeDescription
idempotency_key_in_useThe idempotency key has already been used for a different request.