Error handling
Paypercut uses conventional HTTP response codes and a structured error object to describe why a request failed.
Your integration should handle errors at two levels:
- HTTP status codes, which indicate whether the request succeeded
- Error details, which describe the specific cause and how to respond
Always log the trace_id returned with an error. Include it when contacting support.
Error response format
When a request fails, the API returns a structured error response.
Example error response
{
"type": "invalid_request_error",
"code": "parameter_invalid",
"param": "company.tax_id",
"message": "Invalid tax ID.",
"trace_id": "trc_123"
}
HTTP status codes
Paypercut uses standard HTTP status codes to indicate the outcome of a request.
400 Bad Request
The request is invalid or contains malformed input.
Typical causes include:
- Missing required fields
- Invalid field values
- Unsupported request combinations
401 Unauthorized
Authentication failed or the request is missing valid credentials.
403 Forbidden
The authenticated principal is not allowed to perform the requested action.
404 Not Found
The requested resource does not exist or is not accessible in the current context.
409 Conflict
The request conflicts with the current state of the resource.
422 Unprocessable Entity
The request is well-formed but cannot be processed in its current state.
429 Too Many Requests
The client has sent too many requests in a given time period.
500 Internal Server Error
An unexpected error occurred while processing the request.
Do not treat all non-2xx responses the same. Your integration should branch on both the HTTP status code and the error details.
Error types
The type field indicates the broad class of error.
Typical categories include:
invalid_request_error— the request is invalidapi_error— the request could not be processed due to an internal or downstream issuecard_error— the payment failed due to card or issuer-related reasonsauthentication_error— authentication failed
Your integration should use the error type as the first branch when deciding how to handle a failed request.
Field-level errors
If an error is associated with a specific request field, the response includes the param field.
Example field-level error
{
"type": "invalid_request_error",
"code": "parameter_invalid",
"param": "card_number",
"message": "Your card number is incorrect. Please check your card details and try again.",
"trace_id": "trc_123"
}
Use param to surface validation messages next to the relevant field in your UI.
Payment errors
For payment failures, the error response may also include:
decline_codeadvice_codenetwork_decline_codenetwork_advice_code
These fields help determine:
- whether the payment can be retried
- whether the customer should use a different payment method
- whether additional authentication is required
See:
Recommended handling strategy
Determine whether the failure is caused by input, authentication, rate limiting, or a processing issue.
Use the error details to classify the failure more precisely.
Use param for field errors, and decline-related fields for payment failures.
Store the trace_id for debugging and support.
Best practices
- Handle validation errors at the field level
- Log all error responses in your backend systems
- Store the
trace_idfor failed requests - Do not retry all API errors automatically
- Use decline and advice codes to drive payment retry behavior
