---
title: Errors
slug: errors
createdAt: 2026-11-02T00:00:00.000Z
---
The Orchestration API uses standard HTTP status codes. A `2xx` status means the request was processed. `4xx` means the request could not be processed as sent, and `5xx` means a problem on Forter's side or with an upstream service.
:::hint{type="info"}
A declined payment is **not** an error. Declines are returned with a success status and the payment in status `failed`. See [Declines and Retries](docId:24TiJspj41bFa8_yyScGt).
:::
## Error Format
Every error response has the same JSON body:
```json
{
"errorCode": "PAYMENT_NOT_FOUND",
"message": "Payment pi_v1r1a3f9c2e4b5d6478a9b0c1d2e3f4a5b6c not found"
}
```
- `errorCode`: a stable, machine-readable code. Branch on this together with the HTTP status.
- `message`: a human-readable explanation, intended for logs and debugging. Its wording may change, so don't parse it.
The response's `X-Correlation-ID` header identifies the request. Include it when you contact Forter support.
## HTTP Status Codes
| Status | Meaning |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200`, `201` | The request was processed. Check the payment or refund `status` in the body. |
| `400` | The request is invalid: a missing or malformed field, an unknown field, a missing `Idempotency-Key`, or an operation that the payment's current status doesn't allow. |
| `401` | Missing or invalid credentials. See [API Basics](docId\:nVc4KjxsJzFFvBuWL1yr6). |
| `404` | The payment or refund doesn't exist, or belongs to another site. |
| `409` | Conflict: a request with the same `Idempotency-Key` is still in progress, or another operation on the same payment is in progress. Retry after a short delay. The exception is `PAYMENT_IDEMPOTENCY_CONFLICT`, which needs a new key. |
| `422` | The request is valid, but can't be completed for this payment. For example, the processor doesn't support the operation, the refund exceeds what is refundable, or the processor refused a re-authorization. |
| `500`, `502` | An unexpected error at Forter or an upstream service. Retry with the same `Idempotency-Key` and exponential back-off. |
## Error Codes
| `errorCode` | HTTP status | Meaning |
| ---------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `INVALID_INPUT` | `400`, `401`, `409` | The request failed validation (`400`), the credentials are missing or invalid (`401`), or a request with the same `Idempotency-Key` is still in progress (`409`). |
| `INVALID_PAYMENT_METHOD` | `400` | The payment token or alias is invalid or has expired. |
| `PAYMENT_NOT_FOUND` | `404` | No payment (or capture) with this ID exists for your site. |
| `PAYMENT_INVALID_STATE` | `400`, `409`, `422` | The payment can't perform this operation right now:
- `400`: the payment's current status doesn't allow the operation, or the processor doesn't support it.
- `409`: another operation on the payment, such as a capture or re-authorization, is still in progress. Retry after a short delay.
- `422`: the request is valid but can't be completed for this payment, for example because the amount exceeds what is refundable or the capture hasn't settled yet. |
| `PAYMENT_IDEMPOTENCY_CONFLICT` | `409` | The `Idempotency-Key` is already held by a pending refund of a different capture. Retry with a new key. |
| `PAYMENT_UNSUPPORTED_CURRENCY` | `400` | No processor configured for your site can process this payment, for example because of its currency. |
| `FRAUD_DECLINE` | `400` | Forter declined the payment. |
| `3DS_REQUIRED` | `400` | The payment requires a successful 3DS authentication to proceed. |
| `3DS_FAILED` | `400` | 3DS authentication failed. |
| `PSP_DECLINED` | `422` | The processor declined a re-authorization. The message includes the normalized response code. |
| `PSP_UNAVAILABLE` | `422` | A re-authorization didn't complete at the processor. Retrieve the payment to check its current state before retrying. |
| `PSP_TIMEOUT`, `PSP_GATEWAY_ERROR` | `5xx` | An upstream service timed out or returned an unexpected result. Retrieve the payment to check its current state before retrying. |
| `INTERNAL_ERROR` | `500` | An unexpected error at Forter. Retry with the same `Idempotency-Key`. Contact support if it persists. |
:::hint{type="info"}
New error codes may be added over time. If you receive a code you don't recognize, handle it according to the HTTP status.
:::
## Handling Errors
- **`4xx`:** don't retry the same request unchanged, except for `409`. Fix the request, or check the payment's current state with `GET /api/payments/{id}`.
- **`409` (except `PAYMENT_IDEMPOTENCY_CONFLICT`), `5xx` and timeouts:** retry with the **same** `Idempotency-Key`, using exponential back-off. For `PAYMENT_IDEMPOTENCY_CONFLICT`, send a **new** key. See [Idempotency](docId:6evvXmGB4xaQjCtRHZlTW).
- **Unsure of the outcome?** Retrieve the payment. Its `status` is the source of truth.