# Errors

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

Source: https://docs.okyc.stream/backend/errors

Errors use HTTP status codes and a JSON body:

```json
{
  "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](https://docs.okyc.stream/backend/idempotency.md).                              |
| `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](https://docs.okyc.stream/reference/errors.md).

## 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.*`.