Authentication Failed

Reference · Errors

authentication_failed401

Authentication · Affects all endpoints

The request couldn't be authenticated. The specific cause isn't disclosed; check credentials and try again.

What this means

A request reached an authenticated endpoint, and authentication failed — but the route deliberately doesn't tell you whether the credential was missing, invalid, revoked, or expired. This is a generic auth failure used by endpoints (internal API, billing webhooks) where disclosing the specific failure mode would leak information. For most user-facing endpoints, you'll see a more specific code (api_key_missing, api_key_not_found, api_key_revoked, api_key_invalid) instead.

When you'll see this

• A request to an internal endpoint used the wrong X-Internal-Secret value.
• A billing or admin route was hit without a valid session.
• A webhook signature check failed.
• An endpoint that's deliberately ambiguous about auth state rejected the request.

Learn more about how this works

The auth layer has two modes. Public endpoints (the bulk of the API) return specific codes because helpful error messages are worth more than the marginal information they leak — "your key is revoked" is far more useful than "auth failed." Internal and high-privilege endpoints flip that calculus: they return authentication_failed and disclose nothing, because the threat model includes attackers probing for valid credentials.

The most common gotcha: this error usually means you're calling an endpoint you didn't realize was internal-only. The public API never returns authentication_failed for missing or wrong API keys — those return specific api_key_* codes. If you're seeing this from /v1/astro/* or /v1/numerology/*, something unusual is happening.

Example response

{
  "success": false,
  "error": "authentication_failed",
  "message": "We couldn't authenticate your request. Verify your credentials and try again.",
  "details": [],
  "retry_after": null,
  "doc_url": "https://docs.asterwise.com/reference/errors/authentication_failed",
  "request_id": "req_01HXYZABCDEFGH",
  "timestamp": "2026-05-25T12:34:56Z"
}

NEW TO APIS?

Quick fix

1. Verify which endpoint you're calling. If it's under /v1/internal/* or /v1/admin/*, you need a different credential type than a standard API key.
2. For dashboard or billing routes, sign in fresh at asterwise.com/dashboard to get a current session token.
3. If you're certain the endpoint is public and your credentials are correct, capture the request_id and contact [email protected].

PRODUCTION ENGINEER

Recovery pattern

Treat as a hard 401. Don't retry; don't infer the cause; route the user to the appropriate sign-in or credentials flow based on which endpoint they were hitting.

Python:

Production handler

Python

import httpx

class AsterwiseAuthError(Exception):
    """Authentication failed. Cause not disclosed by endpoint."""

def call_protected(url, headers, payload):
    response = httpx.post(url, headers=headers, json=payload, timeout=15)
    if response.status_code == 401:
        body = response.json()
        if body.get("error") == "authentication_failed":
            raise AsterwiseAuthError(
                f"Authentication failed for {url}. "
                f"Verify credentials. request_id={body.get('request_id')}"
            )
    response.raise_for_status()
    return response.json()

TypeScript

class AsterwiseAuthError extends Error {}

async function callProtected(url: string, headers: HeadersInit, payload: unknown) {
  const response = await fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(payload),
  });
  if (response.status === 401) {
    const body = await response.json();
    if (body.error === "authentication_failed") {
      throw new AsterwiseAuthError(
        `Authentication failed for ${url}. ` +
        `Verify credentials. request_id=${body.request_id}`,
      );
    }
  }
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return response.json();
}

Avoid this error by

• Keep internal and public credential paths visibly separated in your codebase. A standard API key calling an internal endpoint is a category error, not a config drift.
• Don't share API keys across environments. Production keys for production endpoints; sandbox keys for development.
• For dashboard/billing flows, keep session tokens refreshed and don't let them sit stale across long-running flows.

RELATED ERRORS

api_key_missing

public endpoints return this when no key was sent at all.

api_key_invalid

public endpoints return this when a key has the wrong format.

session_expired

dashboard session timed out; sign in again.

session_not_found

session token doesn't match any active session.