Errors

The error shape, every status the API returns, and the header that tells you which of two 401s you hit.

Errors are a flat object with a human-readable error, and a machine-readable code on the two authentication failures. Every error response is Cache-Control: no-store.

401

{
  "error": "A valid Hawi API key is required.",
  "code": "invalid_api_key"
}

Status	`code`	Means
401	`invalid_api_key`	No `Authorization` header, a header not starting with `Bearer` , or a key that is unknown, expired or rotated.
403	`insufficient_scope`	The key is valid but was not issued with the scope this endpoint requires. Rotation does not fix this; a new key with the right scopes does.
400	—	`{"error": "Invalid page cursor."}` — a cursor that does not decode.
404	—	`{"error": "Workspace not found."}` — not a UUID, not a real workspace, or not this key's workspace. All three are the same response.
429	—	`{"error": "Too many requests. Please wait and try again."}` with `Retry-After`.
503	—	Either load protection is unavailable, or a listing could not be loaded. Retry with backoff.

The WWW-Authenticate header

Both authentication failures set it, and it is the fastest way to tell them apart from a client that only logs status codes.

401  WWW-Authenticate: Bearer realm="hawi", error="invalid_token"
403  WWW-Authenticate: Bearer realm="hawi", error="insufficient_scope"

What to send support

The endpoint and the method.
The status and the code if there was one.
The keyId from /api/v1/auth — never the key itself.
The approximate time, with a timezone.