Errors

The JSON error envelope, the status codes the agent and console APIs return with real example messages, and agent-specific failures.

Last updated

On this page

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.

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

StatusExample errorLikely cause
400unknown control pathBad input — here, a control path outside the allowlist
401—Not logged in, or an invalid agent API key
403forbidden: analytics access requiredAuthenticated, 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
429too many attempts — try again laterRate limited — see 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, because the console calls the agent server-side.

For dashboard-level symptoms rather than raw API responses, see Common errors.

Next steps