Errors & Idempotency

Error format

The OpenAPI spec does not currently document a formal, machine-readable error body schema — each error response is defined with only a one-line description string (e.g. "Bad Request", "Unauthorized"), not a response body schema. In practice the API returns error details as JSON, in a shape similar to RFC 7807 Problem Details, for example:

{
  "type": "https://api.kartapay.me/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "purchase.total.value must be a positive integer string"
}

Treat this as illustrative rather than guaranteed — the exact fields returned may vary, since the spec does not pin them down. At minimum, rely on the HTTP status code below; use the JSON body's contents (if present) for logging/debugging, not for control flow.

Status codes documented in the OpenAPI spec that you should handle explicitly:

Status	Meaning
400	Bad request — the request was malformed or failed validation
401	Missing or expired access token — request a new one (see Authentication)
403	Token valid but not authorized for this resource
404	Resource not found
500	Internal server error — retry later; contact support if it persists

Idempotency

Use a unique clientId per payment (see Create a Payment) so you can safely retry a request after a network error without risking a duplicate payment — check for an existing payment with that clientId before creating a new one if a request times out.