Errors can occur at different stages of the payment lifecycle:

API validation layer/HTTP status-level errors (before processing starts)
Processing layer - Payins (after payment initiation)
Processing layer - Payouts (business validation / execution stage)

HTTP Status Codes

These are transport-level responses from the API.

Status Code	Meaning	When It Happens
`400 Bad Request`	Validation failed	Missing or invalid request parameters
`401 Unauthorized`	Authentication failed	Invalid or missing API key/Token
`403 Forbidden`	Access denied	Service not allowed or insufficient permissions
`404 Not Found`	Resource not found	Invalid endpoint or entity ID
`409 Conflict`	Duplicate request	Resource already exists
`500 Internal Server Error`	Unexpected server error	System failure

Validation Errors (400)

When request validation fails, the API responds with:

{
  "errors": [
    {
      "code": "ValidationError",
      "message": "Order amount should be positive."
    }
  ]
}

Possible Validation Messages

Order amount should be positive.
Currency is required.
Order information is required.
Payer information is required.
RedirectUrl is required.

How to handle: Fix the request payload and resend.

Payin Processing Decline Reasons

These occur after payment initiation when the financial institution or risk engine responds.

Code	Description	Meaning
`BLOCKED BY RISK`	Blocked by risk engine	Transaction declined by fraud/risk controls
`FORM EXPIRED`	Payment session expired	User did not complete payment in time
`FAILED TO RECEIVE ACCOUNT INFORMATION`	Account data missing	Bank did not return required account details
`FINANCIAL INSTITUTION: INITIATION FAILED`	Bank initiation failed	Technical failure during bank initiation
`FINANCIAL INSTITUTION: INITIATION REJECTED`	Bank rejected initiation	Bank explicitly declined the payment

These are returned as processing status details, not HTTP validation errors. For example response in the webhook for failed payment:

{
  "Id": "c1f4a9d2-8b73-4e61-9c2e-5d7f3a1b92e4",
  "Status": "Failed",
  "OrderId": "9a7e2c41-3d55-4f8b-a2c9-1e6d4b7f0c33",
  "Reference": "XZ92LM4Q8T7KP3R",
  "Currency": "EUR",
  "Amount": 47.50,
  "Payer": {
    "Name": "Max Mustermann",
    "BankId": "ing_de",
    "Account": {
      "Iban": "DE12500105170648489890"
    }
  },
  "CompletedDate": null,
  "RejectReason": "FORM EXPIRED",
  "EventId": "a8b3c6d9-5f21-4a7e-b8c2-9d4e6f1a2b77",
  "EventTimestamp": 1775623498123
}

Payout Processing Errors

These are business validation errors during payout execution.

Category	Error Message	Description / Notes
Validation	`Payee Name is invalid, name should contain First Name and Last Name`	The payee’s name does not include both first and last name.
Validation	`Currency is incorrect, should be EUR`	The provided currency is not supported.
Validation	`CallbackUrl is not a valid URL`	The callback URL is invalid or malformed.
Validation	`Payee Invalid IBAN format`	The IBAN provided does not match the required format.
Validation	`Amount must have at most 2 decimal places`	The requested payout amount exceeds allowed precision.
Business Rule	`Payouts already exist`	A payout with the same details already exists.
Business Rule	`Requested amount exceeds limit`	The requested amount is higher than the allowed limit.

Response body for failed payout:

{
  "Id": "trf_4f2d9b8c-7a5e-4c1f-9d6b-987654fedcba",
  "Status": "Failed",
  "Amount": 780.50,
  "Currency": "USD",
  "OrderId": "67890",
  "Payee": {
    "Name": "Jane Smith",
    "Account": {
      "Iban": "DE75512108001245126199"
    }
  },
  "RejectReason": "Currency is incorrect, should be EUR",
  "CreatedAt": "2025-12-05T15:30:00.000Z",
  "Reference": "OUT-20251205-007",
  "EventId": "c7e2d1f9-3b4a-4a5e-8c2f-1234abcd5678",
  "EventTimestamp": 1772008800000
}

How to handle: Correct the request data and resend. Validation errors must be fixed before retrying.