Error handling

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

---

Error envelope

{
  "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

• Rate limits