unauthenticated

HTTP 401Unauthorized

The request carried no bearer token, or the token was not recognised.

Every request to the Ahoy API must send Authorization: Bearer <key>. This error means the header was missing, malformed, or the key it carried does not resolve to an active principal.

Response shape

{
  "type": "https://api-docs.ahoy.ai/rest/v1/errors/unauthenticated",
  "title": "Unauthorized",
  "status": 401,
  "detail": "The Authorization header is missing or malformed.",
  "code": "unauthenticated",
  "request_id": "req_01J8Z2K9QW3X4Y5Z6A7B8C9D"
}

reason sub-codes

A reason narrows unauthenticated to a specific cause. New values are additive and never require a version bump, so treat an unrecognised reason as the bare unauthenticated.

reason	Meaning
resolver_error	The credential service could not be reached. This is transient — retry.

How to resolve it

• Check the Authorization header is present and formatted as Bearer <key>, with a single space.
• Confirm the key has not been revoked in Settings → API & Service Accounts.
• Keys are scoped to one org. A key minted in another org will not authenticate here.