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.

