# Errors

> The JSON error envelope, the status codes the agent and console APIs return with real example messages, and agent-specific failures.
>
> Canonical: https://xdp.network/docs/api-reference/errors · Updated 2026-08-09

Both APIs report failures the same way: a conventional HTTP status code and a small
JSON body with a single `error` string. Read the string before debugging — it names
the problem in most cases.

```json title="Error envelope"
{ "error": "message describing what went wrong" }
```

Use the status code to decide where to look first: a `4xx` means the request itself
needs fixing, while a `502` means the console never got an answer from your agent, so
start on the server rather than in the dashboard.

## Status codes

| Status | Example `error` | Likely cause |
| --- | --- | --- |
| 400 | `unknown control path` | Bad input — here, a control `path` outside the allowlist |
| 401 | — | Not logged in, or an invalid agent API key |
| 403 | `forbidden: analytics access required` | Authenticated, but missing the required permission |
| 404 | — | The server, ticket, or other resource does not exist |
| 409 | — | Conflict — e.g. registering with an email already in use |
| 413 | — | Request body too large |
| 429 | `too many attempts — try again later` | Rate limited — see [Rate limits](/docs/api-reference/rate-limits) |
| 502 | — | The console could not reach your agent |

## Agent-specific failures

Three failures dominate when you query the agent's metrics API directly:

- **`401`** — the `osk_` key is wrong or has been rotated. Print the current one with
  `openshield key`.
- **`403`** — the key is valid, but the calling IP is not in `metrics.whitelist` in
  `/etc/openshield/openshield.yaml`.
- **Timeouts** — slow responses usually mean the agent is applying a large geo or feed
  update. Setting `auto_fetch.mode: dedicated` (the recommended value) keeps those
  updates from stalling responses.

Through the console, the same reachability problems surface as `502` from the
[metrics proxy](/docs/api-reference/endpoints), because the console calls the agent
server-side.

For dashboard-level symptoms rather than raw API responses, see
[Common errors](/docs/troubleshooting/common-errors).

## Next steps

- [Common errors](/docs/troubleshooting/common-errors)
- [Rate limits](/docs/api-reference/rate-limits)
- [Enabling metrics](/docs/openshield-xdp/enabling-metrics)