Errors
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.
A declined payment is not an error. Declines are returned with a success status and the payment in status failed. See Declines and Retries.
Error Format
Every error response has the same JSON body:
{
"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. |
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:
|
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. |
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.
- Unsure of the outcome? Retrieve the payment. Its status is the source of truth.