unauthorized

HTTP 401 · Unauthorized

Example response

{
  "error": {
    "code": "unauthorized",
    "message": "Missing API key."
  },
  "meta": {
    "request_id": "a1b2c3d4-...",
    "latency_ms": 0
  }
}

What happened

The Authorization header was absent, the key format was invalid, or the key has been revoked. Authentication happens before any other processing. This error costs no quota.

How to fix

Why authentication runs first

unauthorized is the cheapest error vatverify can return: it short-circuits before any quota counting, registry lookup, or plan-gate check. The trade-off is that downstream errors mask each other. If your key is revoked, you will see unauthorized even on requests that would have failed for other reasons (rate limit, plan gate, format). Fix the auth issue first, then the next layer of errors becomes visible.

For debugging, the request_id in the response is the key piece of context. vatverify retains request logs for support purposes; producing the request_id lets us trace exactly which key was attempted and at what time.

Key prefixes

vatverify keys follow a fixed prefix scheme:

• vtv_live_: live keys, count against quota and plan gates apply.
• vtv_test_: test-mode keys, return deterministic synthetic data, never count quota, bypass plan gates.

A key that does not start with one of these prefixes will fail the format check and return unauthorized without a registry lookup. If you suspect your environment is mangling the key (whitespace, BOM, copy-paste artifacts), the prefix mismatch is usually the first symptom.

Common mistakes

• Missing the Bearer prefix: the value must be Bearer vtv_live_xxx, not just vtv_live_xxx.
• Passing the key as a query param: ?api_key=vtv_live_xxx is not supported. The header is required.
• Using a test key for integration tests against endpoints that need a live key: test keys work everywhere; the reverse is not true.
• Whitespace around the key: trailing newlines from env file parsing (vtv_live_xxx\n) will cause this error.
• Key revoked from a different team member's dashboard: keys revoked by anyone with access cannot be restored. Generate a new one.

Related errors

• plan_required: key is valid but the endpoint requires a higher plan
• rate_limited: key is valid but quota is exhausted
• webhook_limit_reached: webhook slots full