Response Codes

Koard uses standard HTTP status codes.

Code	Meaning
`200`	Success
`201`	Resource created
`400`	Validation failure — check the response body for 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`	Locked — merchant account is blocked and cannot perform this operation
`429`	Rate limited — slow down and retry
`500`	Unexpected server error

Error Body Format

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

When an error is returned as the structured envelope, the error field is one of:

`error`	HTTP	`message`
`validation_error`	400	Request validation failed
`authentication_required`	401	Authentication required
`permission_denied`	403	Permission denied
`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

Authentication