This document outlines the standard error handling and status codes used across all Payconiq public APIs, including Payments, Refunds, and Merchant Reconciliation.
Payconiq APIs use conventional HTTP response codes to indicate success or failure.
| Status Code | Description |
|---|---|
200 | OK – The request was successful. |
201 | Created – The resource was successfully created. |
204 | No Content – The request was successful, and there is no content to return. |
| Status Code | Description |
|---|---|
400 | Bad Request – The request is malformed or contains invalid parameters. |
401 | Unauthorized – API key or credentials are missing or invalid. |
403 | Forbidden – You are not allowed to perform this action. |
404 | Not Found – The requested resource could not be found. |
409 | Conflict – The request could not be completed due to a conflict. |
422 | Unprocessable Entity – The request is semantically incorrect. |
429 | Too Many Requests – Rate limit exceeded. |
500 | Internal Server Error – An unexpected error occurred on the server. |
503 | Service Unavailable – Temporary server overload or maintenance. |
Payment statuses reflect the lifecycle stage of a transaction. Satuses may be final or intermediary. Once a transaction hits a final status, the status will not change again.
Payment statuses are included in the body of the following calls:
- Create Payment Response
- Get Payment Details Response
- Search Payment Response
- Callback request
| Status Name | Status | Description |
|---|---|---|
PENDING | Intermediary | The transaction has been created but not yet initiated by the user. |
IDENTIFIED | Intermediary | The user has interacted with the transaction (e.g., scanned QR code). |
AUTHORIZED | Intermediary | The transaction has passed initial verification and is ready for final processing. |
AUTHORIZATION_FAILED | Final | The transaction failed bank-side validation. Common reasons: insufficient funds, card limits. |
SUCCEEDED | Final | The transaction was completed successfully. |
FAILED | Final | The transaction failed due to a technical or logical error. |
CANCELLED | Final | The transaction was explicitly cancelled. |
EXPIRED | Final | The transaction was not completed in time and has expired. |
PENDING_MERCHANT_AKNOWLEDGMENT | Intermediary | The transaction has been confirmed by the consumer and is pending aknowledgement from the Merchant. Applicable only when VOID is active. |
VOIDED | Final | The transaction has been voided after consumer confirmation. Applicable only when VOID is active. |
Error responses are standardized across APIs and follow this structure:
{
"code": "UNAUTHORIZED",
"message": "API key is missing or invalid.",
"traceId": "abc123xyz456",
"spanId": "op789trace"
}| Attribute | Description |
|---|---|
code | Unique error identifier. Use this to programmatically react to specific errors. |
message | Human-readable message describing the issue. |
traceId | Identifier for tracing the error in logs. Provide this when contacting support. |
spanId | Operation-level identifier, useful for distributed tracing. |
| Code | Description |
|---|---|
UNAUTHORIZED | The API key or credentials are invalid or missing. |
ACCESS_DENIED | The authenticated user or key does not have permission to access the resource. |
PAYMENT_NOT_FOUND | No payment found for the specified ID. |
REFUND_NOT_FOUND | The refund does not exist or cannot be accessed. |
TECHNICAL_ERROR | A backend system error occurred. Try again later or contact support. |
CALLER_NOT_ALLOWED_TO_CANCEL | You do not have permission to cancel this payment. |
PAYMENT_NOT_PENDING | The requested operation is invalid because the payment is no longer pending. |
PAYMENT_CONFLICT | The resource is in conflict (e.g., duplicate operation). |
BODY_MISSING | The HTTP request body is empty when one was expected. |
FIELD_REQUIRED | One or more required fields are missing. |
QR_NO_LONGER_IN_USE | The QR code has expired or is no longer valid. |
UNABLE_TO_PAY_CREDITOR | Payout to merchant failed. |
TRY_AGAIN_LATER | Temporary failure – the operation may succeed if retried after a delay. |
Log
traceIdandspanId: These identifiers help Payconiq investigate issues efficiently.Differentiate error classes:
- 4xx: Client errors – fix request content.
- 5xx: Server errors – retry with exponential backoff.
Rate limiting: Respect HTTP 429 responses with retry-after logic.
Monitoring: Track recurring error codes to detect integration issues early.
If persistent or unexplained issues occur, contact devsupport@payconiq.be with error details and traceId.