API Key Invalid
api_key_invalid401
The credential sent isn't shaped like an Asterwise API key. Check the format and try again.
What this means
A credential was included in the request, but it doesn't match the structural shape of an Asterwise API key. Asterwise keys start with aw_ followed by at least 40 URL-safe characters. The check happens at the format layer, before any database lookup — so this error fires whether the credential is malformed garbage or a perfectly valid key from a different system being used in the wrong place.
When you'll see this
- A key from another service was accidentally pasted into the Asterwise client config.
- A truncated key was used (e.g. only the
aw_prefix without the body, or the body without the prefix). - A key was URL-encoded or otherwise transformed before being sent.
- A whitespace or quote character is embedded in the key string.
- A JWT or session token was sent in place of an API key.
Learn more about how this works
Asterwise keys are deterministically formatted: aw_ prefix + URL-safe random tail (letters, digits, hyphens, underscores). Anything not matching that pattern gets api_key_invalid immediately, without consulting the database. This is intentional: if your config has the wrong type of credential entirely, we want to tell you that fast, before logging a "key not found" event against a value that was never meant to be a key.
In practice: this error is almost always a config or copy-paste issue. The key character set doesn't include spaces, plus signs, equals signs, or quotes — if your key has any of those, something transformed it after generation. Original keys come out clean from the dashboard.
Example response
{
"success": false,
"error": "api_key_invalid",
"message": "Invalid API key format.",
"details": [],
"retry_after": null,
"doc_url": "https://docs.asterwise.com/reference/errors/api_key_invalid",
"request_id": "req_01HXYZABCDEFGH",
"timestamp": "2026-05-25T12:34:56Z"
}
- Get a fresh key from asterwise.com/dashboard and copy it directly — no transformations, no manual edits.
- Confirm the key starts with
aw_and has no spaces, quotes, or extra characters. - If the key looks correct in your config but the request still fails, log the exact bytes being sent and compare character-by-character with what the dashboard shows.
This is a config error in your client. Don't retry; surface clearly.
Python:
Production handler
- Python
- TypeScript
import httpx
import re
_KEY_PATTERN = re.compile(r"^aw_[A-Za-z0-9_-]{40,}$")
def validate_key(key: str) -> bool:
"""Pre-flight check before sending requests."""
return bool(_KEY_PATTERN.match(key))
def call_asterwise(url, api_key, payload):
if not validate_key(api_key):
raise ValueError(
"Asterwise API key has wrong format. "
"Expected 'aw_' followed by 40+ URL-safe characters."
)
headers = {"Authorization": f"Bearer {api_key}"}
response = httpx.post(url, headers=headers, json=payload, timeout=30)
response.raise_for_status()
return response.json()
const KEY_PATTERN = /^aw_[A-Za-z0-9_-]{40,}$/;
function validateKey(key: string): boolean {
return KEY_PATTERN.test(key);
}
async function callAsterwise(url: string, apiKey: string, payload: unknown) {
if (!validateKey(apiKey)) {
throw new Error(
"Asterwise API key has wrong format. " +
"Expected 'aw_' followed by 40+ URL-safe characters.",
);
}
const response = await fetch(url, {
method: "POST",
headers: { Authorization: `Bearer ${apiKey}` },
body: JSON.stringify(payload),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
return response.json();
}
Avoid this error by
- Validate keys at config-load time using the format above. Catch corrupted or wrong-type credentials before they reach any HTTP call.
- Never trim, encode, or transform keys after copying them from the dashboard. They're delivered in their final form.
- Don't store keys in YAML or JSON files where they might get auto-quoted, escaped, or normalized. Use environment variables or a proper secrets manager.
- In CI logs, mask the key entirely. A truncated key in a log looks like a debugging artifact and tempts someone to "restore" it incorrectly.