When interacting with the PPRO API, requests that cannot be processed successfully will return an HTTP error. Errors are classified into client errors (4xx) and server errors (5xx). The response body typically includes a status code and a descriptive failureMessage to help diagnose the issue.
Client errors (4xx)
Client errors indicate that the request sent to the API is invalid or cannot be processed due to client-side issues.
| Status Code | Description | Example |
|---|---|---|
| 400 Bad Request | The request is invalid or malformed. | Malformed JSON, missing required parameters, invalid data formats |
| 401 Unauthorized | The client is not authenticated. | Missing or invalid authentication details |
| 403 Forbidden | The client is authenticated but does not have permission to perform the requested action. | Trying to access a restricted endpoint |
| 404 Not Found | The requested resource does not exist. | Retrieving a charge or operation using an unknown ID |
| 405 Method Not Allowed | The HTTP method used is not supported for the requested resource. | Using POST on a resource that only supports GET |
| 409 Conflict | The request could not be completed due to a conflict. | Duplicate resource creation, idempotency key conflict |
| 415 Unsupported Media Type | The request contains an unsupported content type. | Sending XML when the API expects JSON |
| 422 Unprocessable Entity | The request is well-formed but contains semantic errors. | Invalid field value (e.g., negative amount for a payment) |
| 429 Too Many Requests | The client has exceeded rate limits. | Sending too many requests in a short time (rate limiting) |
| 431 Request Header Fields Too Large | One or more request headers are too large. | Sending overly large authentication tokens or custom headers |
Server errors (5xx)
Server errors indicate that the request could not be processed due to an issue on the PPRO side. These errors are typically temporary and may succeed if retried later.
Responses for client and server errors follow a consistent JSON format:
{
"status": 404,
"failureMessage": "Payment charge not found",
"timestamp": "2025-02-17T21:18:20.003Z"
}Failures and declines in accepted requests (2xx)
When you create a resource, the request may be accepted for processing by the PPRO system, but the underlying operation may still fail or be declined. A common example is when a payment charge is successfully created, but the authorization is subsequently declined by the payment provider.
In these cases, the API returns an HTTP 2xx response with the created entity. The entity’s payload includes detailed information describing the failure.
Example responses for a failed capture request:
{
"id": "capture_JSyqZHmo3YMmETUEH5xxa",
"amount": 90000,
"status": "FAILED",
"merchantCaptureReference": "YOUR_CAPTURE_REFERENCE",
"failure": {
"failureType": "INTERNAL_DECLINE",
"failureCode": "EXCEEDS_AUTHORIZED_AMOUNT",
"failureMessage": "Insufficient authorized funds to process the capture request"
},
"createdAt": "2025-11-03T20:47:13.584Z",
"updatedAt": "2025-11-03T20:47:13.584Z",
"_links": {
"payment_charge": {
"href": "/v1/payment-charges/charge_a0Z6aJuBJcFheGJ6XSkyW"
}
}
}Every failed operation (discard, authorization, void, capture, refund) includes a failure object with the following fields:
Field | Description |
|---|---|
| The general category of failure. Possible values: |
| (Optional) An internal code generated by PPRO identifying the specific failure. |
| (Optional) A failure code returned by the upstream provider. |
| A human-readable message describing the cause of the failure. |
| (Optional) Indicates whether the operation can be safely retried. |
A Payment Charge will always contain a
failureobject with a copy of the most recent failure that has occurred in any associated operation.{ "id": "charge_a0Z6aJuBJcFheGJ6XSkyW", "paymentMethod": "CARD", "paymentMedium": "ECOMMERCE", "scheduleType": "UNSCHEDULED", "instrumentId": "instr_kr6RS3kQSjXRHqDst0MDN", "instrumentUpdated": false, "currency": "BRL", "country": "BR", "networkTransactionIdentifier": "060720116005060", "status": "CAPTURE_PENDING", "consumer": { "name": "John Smith", "country": "BR" }, "failure": { "failureType": "INTERNAL_DECLINE", "failureCode": "EXCEEDS_AUTHORIZED_AMOUNT", "failureMessage": "Insufficient authorized funds to process the capture request" }, "authorizations": [ { "id": "authz_ltLjumN5AOcmpwN0XkMhz", "amount": 10000, "status": "AUTHORIZED", "schemeAuthorizationReference": "060720116005060", "createdAt": "2025-11-03T20:46:21.813Z", "updatedAt": "2025-11-03T20:46:21.813Z" } ], "captures": [ { "id": "capture_JSyqZHmo3YMmETUEH5xxa", "amount": 90000, "status": "FAILED", "merchantCaptureReference": "YOUR_CAPTURE_REFERENCE", "failure": { "failureType": "INTERNAL_DECLINE", "failureCode": "EXCEEDS_AUTHORIZED_AMOUNT", "failureMessage": "Insufficient authorized funds to process the capture request" }, "createdAt": "2025-11-03T20:47:13.584Z", "updatedAt": "2025-11-03T20:47:13.584Z" } ], "refunds": [], "discards": [], "voids": [], "createdAt": "2025-11-03T20:46:20.623Z", "updatedAt": "2025-11-03T20:47:13.584Z", "_links": { "authorizations": { "href": "/v1/payment-charges/charge_a0Z6aJuBJcFheGJ6XSkyW/authorizations" }, "captures": { "href": "/v1/payment-charges/charge_a0Z6aJuBJcFheGJ6XSkyW/captures" }, "refunds": { "href": "/v1/payment-charges/charge_a0Z6aJuBJcFheGJ6XSkyW/refunds" }, "discards": { "href": "/v1/payment-charges/charge_a0Z6aJuBJcFheGJ6XSkyW/discards" }, "voids": { "href": "/v1/payment-charges/charge_a0Z6aJuBJcFheGJ6XSkyW/voids" } } }