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
`failureType`	The general category of failure. Possible values: `INTERNAL_ERROR`: An unexpected error occurred within PPRO’s system. `INTERNAL_DECLINE`: PPRO determined that the operation should be declined. `PROVIDER_ERROR`: An error occurred while communicating with an upstream provider. `PROVIDER_DECLINE`: The upstream provider declined the operation.
`failureCode`	(Optional) An internal code generated by PPRO identifying the specific failure.
`providerFailureCode`	(Optional) A failure code returned by the upstream provider.
`failureMessage`	A human-readable message describing the cause of the failure.
`isRetryable`	(Optional) Indicates whether the operation can be safely retried.

📘

A Payment Charge will always contain a failure object 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"
    }
  }
}