> For the complete documentation index, see [llms.txt](https://kreatorverse-2.gitbook.io/kollect-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kreatorverse-2.gitbook.io/kollect-documentation/reference/error-handling.md).

# Error handling

Kollect S2S endpoints return structured JSON errors for predictable client handling.

***

## Error envelope

```json
{
  "success": false,
  "error": {
    "code": "INVALID_PAYMENT_DATA",
    "message": "Human-readable message",
    "timestamp": "2025-03-23T12:00:00.000Z",
    "requestId": null,
    "details": {}
  }
}
```

| Field       | Description                                                                      |
| ----------- | -------------------------------------------------------------------------------- |
| `code`      | Machine-readable error code (string).                                            |
| `message`   | Human-readable explanation.                                                      |
| `timestamp` | ISO 8601 time of the error.                                                      |
| `requestId` | May be populated when request-id middleware is enabled.                          |
| `details`   | Optional object for **4xx** errors (e.g. idempotency metadata, rate limit info). |

HTTP status codes align with the error class (e.g. `400` for validation, `401` for auth, `409` for conflicts).

***

## Common error codes

| Code                        | Typical HTTP | Meaning                                                |
| --------------------------- | ------------ | ------------------------------------------------------ |
| `INVALID_API_KEY`           | 401 / 403    | Missing, wrong, or inactive API credentials.           |
| `INVALID_SIGNATURE`         | 401          | HMAC verification failed.                              |
| `REQUEST_EXPIRED`           | 400 / 401    | Timestamp missing, invalid, or outside allowed window. |
| `IDEMPOTENCY_REQUIRED`      | 400          | `X-Idempotency-Key` missing.                           |
| `IDEMPOTENCY_CONFLICT`      | 409          | Same idempotency key reused with different body.       |
| `DUPLICATE_REQUEST`         | 409          | Concurrent duplicate idempotent request.               |
| `RATE_LIMIT_EXCEEDED`       | 429          | Too many requests (invalid auth or per-key limits).    |
| `INVALID_PAYMENT_DATA`      | 400          | Validation failed (Joi).                               |
| `DUPLICATE_INVOICE`         | 409          | Invoice number already exists for merchant.            |
| `PAYMENT_PROCESSING_FAILED` | 400          | Business error (e.g. deposit wallet not configured).   |
| `INVOICE_CREATION_FAILED`   | 400          | Mapped invoice creation failures.                      |
| `INTERNAL_ERROR`            | 500          | Unexpected server error.                               |

***

## Related pages

* [Create payment URL](/kollect-documentation/api-reference/create-payment.md)
* [Rate limits](/kollect-documentation/reference/rate-limits.md)