Errors Representation

Standard errors representation

When you send a request to the PPRO API and it is rejected (e.g., due to a system failure), you will receive an HTTP 400 or 500 error.

• HTTP 400 Bad Request
  Invalid request (e.g., incorrect parameters or malformed data)
  Invalid operation (e.g., attempting an operation on an unknown charge ID)
  Invalid instrument ID (e.g., creating a charge with an unknown instrument ID)
  Refused operation (e.g., trying to refund an non-captured charge)
• HTTP 404 Not Found
  Resource not found (e.g., attempting to retrieve a charge or an operation using an unknown ID)
• HTTP 500 Internal Server Error
  System failure (e.g., failure to connect to a database)

Responses have the following format:

{
  "status": 404,
  "failureMessage": "Payment charge not found",
  "timestamp": "2025-02-17T21:18:20.003Z"
}

Failures and Declines in Accepted Requests

When you send a request to create a Payment Charge, Payment Agreement or Payment Report operation, the request may be accepted for processing by our system, but the desired operation could not be fulfilled. In these cases, you will receive a HTTP 200 response with the created entity, which contains information about the failure.

Example responses for failed Payment Charge operations:

Response (HTTP 200):

{
  "id": "charge_UyreKG7bBuHE8VhwhpG8I",
  "paymentMethod": "KLARNA_BNPL",
  "status": "FAILED",
  
  "failure": {
    "failureType": "PROVIDER_DECLINE",
    "internalFailureCode": "some-internal-failure-code",
    "providerFailureCode": "some-provider-failure-code",
    "failureMessage": "Failed to create credit session"
  },
  
  "authorizations": [
    {
      "id": "authz_zNSICpiwfevcOwcZGgqVJ",
      "amount": 15000,
      "status": "FAILED",
      "failure": {
        "failureType": "PROVIDER_DECLINE",
        "failureCode": "some-internal-failure-code",
        "providerFailureCode": "some-provider-failure-code",
        "failureMessage": "Failed to create credit session"
      },
    }
  ],
  ... // other fields
}

Response (HTTP 200):

{
  "id": "refund_yT763oF6Z6m3xlDsd122V",
  "amount": 1000,
  "status": "FAILED",
  
  "failure": {
    "failureType": "PROVIDER_DECLINE",
    "internalFailureCode": "internal-failure-code",
    "providerFailureCode": "provider-failure-code",
    "failureMessage": "Refund was declined"
  },
}

Every failed Authorization, Capture, Refund and Void operation includes a failure object with the following fields:

📘

A Payment Charge will always contain a copy of the most recent failure that has occurred in an underlying Authorization, Capture, Refund or Void.