Response Codes

Koard uses standard HTTP status codes.

Code Meaning
200 Success
201 Resource created
400 Request rejected. Check the error code and details.
401 Missing or invalid API key
403 Insufficient permissions for this operation
404 Resource not found
409 Conflict: resource already exists or state mismatch
423 The merchant account or location is blocked and cannot perform this operation
429 Rate limited: slow down and retry
500 Unexpected server error

Error Body Format

Most errors return a structured envelope with a machine-readable error code, a short message category, and a human-readable details string. Branch on error in client code; details is always a string (never a list or object):

{
  "error": "validation_error",
  "message": "Request validation failed",
  "details": "query: sort_by: Input should be 'name' or 'volume'"
}

500 responses never leak internal exception messages or stack traces: the incident is logged server-side and details carries only a generic string.

Envelope Error Codes

Common envelope error codes include the following. The downloadable API references define the full ErrorType enum.

error HTTP message
validation_error 400 Request validation failed
feature_not_supported 400 Feature not supported
authentication_required 401 Authentication required
permission_denied 403 Permission denied
blocked_merchant 423 Merchant is blocked
blocked_location 423 Location is blocked
not_found 404 Resource not found
conflict 409 Resource state conflict
rate_limited 429 Rate limit exceeded
upstream_error 502 Upstream processor error
internal_error 500 Internal server error

Batch Close Responses

POST /v1/batches/{batch_id}/close can return a Batch object with HTTP 200, 409, or 502 for a processor settlement response. Those Batch responses do not use the error envelope above. Inspect status, response, and rejection_reason; HTTP 200 alone does not establish settlement acceptance.

Other failures can return the error envelope, including a 409 state conflict or a 503 unresolved release. Check the response body before handling it as a Batch object. See Running Batches.

A timeout or server error during a payment operation does not establish that the processor declined it. Use outcome recovery before submitting again.