Errors

One error shape for every endpoint; branch on type and code, log the request id.

Errors use HTTP status codes and a JSON body:

{
  "error": {
    "type": "invalid_request",
    "code": "unsupported_check",
    "message": "…",
    "param": "key",
    "request_id": "req_…"
  }
}

Field	Use
`type`	The category — decides what to do (fix the request, re-authenticate, retry…).
`code`	The specific reason. Stable; safe to branch on.
`message`	For developers and logs; may change. Don't show it to applicants as-is.
`param`	The request field at fault, when there is one.
`request_id`	Include it when you contact support.

Types

Type	HTTP	What to do
`invalid_request`	400	Fix the request; retrying won't help.
`authentication`	401	Check the API key (or, in the flow, the client token).
`permission`	403	The key or user may not do this (role, mode, IP allowlist).
`not_found`	404	Wrong id, or it belongs to the other mode (test vs live).
`conflict`	409	The resource is in the wrong state (e.g. the session is closed).
`idempotency`	409	See idempotency.
`rate_limit`	429	Back off; honour `Retry-After`.
`provider_unavailable`	503	An upstream source is down. Retry later.
`internal`	500	Our fault. Retry with backoff; contact support with the `request_id`.

Every code the API can return is listed in the generated error code reference.

In `@okyc/node`

Errors are typed by type, and every error has type, code, param, requestId and statusCode:

Class	For
`InvalidRequestError`	`invalid_request`
`AuthenticationError`	`authentication`
`PermissionError`	`permission`
`NotFoundError`	`not_found`
`ConflictError`	`conflict` and `idempotency`
`RateLimitError`	`rate_limit` (with `retryAfter` in seconds)
`ProviderUnavailableError`	`provider_unavailable`
`ConnectionError`	network failure or timeout (the request may or may not have reached the API)
`ApiError`	base class of all of them

They're exported from the package and available as Okyc.errors.*.

TypesCopy Anchor Link

In @okyc/nodeCopy Anchor Link

On this page

Types

In `@okyc/node`