# API Errors, Statuses, and Responses

This document outlines the standard error handling and status codes used across all Payconiq public APIs,
including Payments, Refunds, and Merchant Reconciliation.

## HTTP Status Codes

Payconiq APIs use conventional HTTP response codes to indicate success or failure.

### Success Responses

| 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. |


### Error Responses

| 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

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 Response Structure

Error responses are standardized across APIs and follow this structure:


```json
{
  "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. |


## Common Error Codes

| 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. |


## Best Practices for Error Handling

* **Log `traceId` and `spanId`**: 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](mailto:devsupport@payconiq.be) with error details and `traceId`.