Errors

A request can fail in two ways, and your code needs to handle both.

KalHR refused it at the door. The key is wrong, the endpoint isn't open to keys, or you're sending too fast. The answer has an error status code: 401, 403, 429 and so on.
KalHR understood it but couldn't do it. The record isn't in your organisation, or a value isn't allowed. The answer is HTTP 200 with isSuccessful: false and a message saying why.

{
  "isSuccessful": false,
  "code": "01",
  "message": "Employee not found"
}

So check the status code and isSuccessful. The helper on Requests and responses does both.

Status codes

Code	What happened	What to do
`200`	KalHR answered.	Check `isSuccessful`. Read `data`, or log `message` when it's `false`.
`400`	The request couldn't be read: a malformed id, date or body. The `message` names the field.	Fix the request. Retrying won't help.
`401`	The key is missing, mistyped, revoked or expired. The `message` says which.	Check the key. If it was revoked or expired, ask for a new one.
`403`	The key is valid but can't do this. Either the endpoint isn't part of the public API, or the key lacks the access it needs; the `message` names it.	Ask an administrator to give the key that access, or use an endpoint from the reference.
`404`	No such endpoint.	Check the path against the reference.
`409`	A request with the same `Idempotency-Key` is still being processed.	Wait a few seconds and retry with the same key.
`422`	That `Idempotency-Key` was already used for a different request.	Use a new key for a new request.
`429`	Too many requests for this key.	Wait the number of seconds in the `Retry-After` header, then retry.
`500`, `502`, `503`	Something went wrong on KalHR's side.	Retry with backoff. If it persists, contact us with the time of the request.

409, 422 and 429 are explained on Limits and retries.

These come with HTTP 200. The message is written for people and may change wording, so log it but don't match on it. The usual causes:

Not found. The id doesn't exist, or belongs to another organisation. A key never sees another organisation's records; to it they simply don't exist.
A required filter is missing. For example, the payroll list needs a CompanyId.
A value isn't allowed. For example, a CompanyId that isn't one of your organisation's companies.
A value fails the request's checks, such as a PageSize of 0. Only these have code "ValidationError"; every other refusal has "01".

Answer	Retry?
`429`	Yes, after `Retry-After` seconds
`500`, `502`, `503`, a timeout, a dropped connection	Yes, with backoff: wait 1 second, then 2, 4, 8… and give up after a few minutes
`409`	Yes, after a few seconds, with the same `Idempotency-Key`
`400`, `401`, `403`, `404`, `422`	No. Something needs fixing first.
`200` with `isSuccessful: false`	No. The answer won't change until the data does.