API Key Not Found
api_key_not_found401
The key is well-formed but doesn't match any registered Asterwise key. Verify the value in your dashboard.
What this means
The credential in the request is shaped correctly (passes format validation) but doesn't match any key we've issued. Either the key was never valid, was deleted entirely from the account, or there's a transcription error somewhere between the dashboard and your config. The check runs at the database layer — if no record exists for the key hash, this is the response.
When you'll see this
- A typo or transcription error in the key value (one character off).
- An old key from a deleted Asterwise account was reused.
- A staging-environment key was deployed to production where it doesn't exist.
- A key was hard-deleted (not revoked) by an admin action.
- A key from a different SaaS service that happens to match Asterwise's format pattern was used.
Learn more about how this works
We hash incoming keys and look them up against the registered set. If there's no match, we return api_key_not_found rather than disclosing whether the key was once valid. This matters: a "key was deleted" message would be useful for attackers correlating leaked credentials with account states, so we don't provide it. From your perspective, the action is the same regardless: get a fresh key.
The most common gotcha: this error is distinct from api_key_revoked. Revoked means "we know about this key, but it's deactivated" (a soft state, with a record). Not found means "we have no record of this key at all." Both result in the same fix on your end — use a different key — but they reflect different upstream realities.
Example response
{
"success": false,
"error": "api_key_not_found",
"message": "The provided API key was not found. Verify the key in your Asterwise dashboard.",
"details": [],
"retry_after": null,
"doc_url": "https://docs.asterwise.com/reference/errors/api_key_not_found",
"request_id": "req_01HXYZABCDEFGH",
"timestamp": "2026-05-25T12:34:56Z"
}
- Sign in at asterwise.com/dashboard and open the API Keys page.
- Verify the key in your config matches one of the keys listed in the dashboard (compare the first and last few characters — full keys aren't displayed after creation).
- If the key isn't in the list, it doesn't exist — generate a new one and update your config.
This is a config error from your client's perspective. Don't auto-retry; surface clearly so the integration can be fixed.
Python:
Production handler
- Python
- TypeScript
import httpx
import logging
logger = logging.getLogger(__name__)
class AsterwiseKeyMissingError(Exception):
"""Key is well-formed but doesn't match any registered key."""
def call_asterwise(url, headers, payload):
response = httpx.post(url, headers=headers, json=payload, timeout=30)
if response.status_code == 401:
body = response.json()
if body.get("error") == "api_key_not_found":
logger.critical(
"Asterwise key not found in registered set",
extra={"request_id": body.get("request_id")},
)
raise AsterwiseKeyMissingError(
"API key not recognized. "
"Verify the key at asterwise.com/dashboard."
)
response.raise_for_status()
return response.json()
class AsterwiseKeyMissingError extends Error {}
async function callAsterwise(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 === "api_key_not_found") {
console.error("Asterwise key not found in registered set", {
request_id: body.request_id,
});
throw new AsterwiseKeyMissingError(
"API key not recognized. " +
"Verify the key at asterwise.com/dashboard.",
);
}
}
if (!response.ok) throw new Error(`HTTP ${response.status}`);
return response.json();
}
Avoid this error by
- Never hand-type or hand-edit keys. Copy them directly from the dashboard, paste them into a secrets manager, and reference from there.
- Don't share keys across environments. Use a separate key per environment so production lookups always succeed and staging lookups never collide.
- Add a startup health check that calls
GET /v1/keys/me— it validates the key against the live database in one cheap call before serving traffic. - When rotating keys, deploy the new key first, verify with a health check, then revoke the old one. Don't reverse this order.