Response Codes

Koard uses standard HTTP status codes.

Code	Meaning
`200`	Success
`201`	Resource created
`202`	Accepted
`204`	No content
`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
`422`	Request cannot be processed
`423`	Locked — merchant account is blocked and cannot perform this operation
`429`	Rate limited — slow down and retry
`500`	Unexpected server error

Error Body Formats

Koard returns one of two error shapes depending on where the error originates.

Most 4xx errors (401, 403, 404, 409, 423, etc.) return a flat body with a single detail field describing the issue:

{
  "detail": "Terminal not found for the given account"
}

Request-validation failures (400) and server errors (500) 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": "internal_error",
  "message": "Internal server error",
  "details": "An unexpected error occurred. The incident has been logged."
}

The 500 envelope never leaks internal exception messages or stack traces — the incident is logged server-side and you only ever receive the generic details string above.

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

SDK Error Mapping

If you're using the Koard Android SDK, these HTTP status codes are automatically wrapped into KoardException with typed error classifications. You don't need to parse HTTP codes directly — use the KoardErrorType sealed hierarchy instead:

HTTP Code	SDK Error Type	Description
400	`KoardServiceErrorType.HttpError(400)`	Validation failure
401	`KoardServiceErrorType.Unauthorized`	Invalid or expired API key
403	`KoardServiceErrorType.HttpError(403)`	Insufficient permissions
404	`KoardServiceErrorType.NotFound`	Resource not found
409–422	`KoardServiceErrorType.HttpError(code)`	Conflict or processing error
429	`KoardServiceErrorType.HttpError(429)`	Rate limited
500	`KoardServiceErrorType.UnexpectedError`	Server error
Network failure	`KoardServiceErrorType.ConnectionError`	DNS, timeout, or connectivity issue

See the SDK Response Codes & Error Handling guide for the full KoardErrorType reference and code examples.

Authentication