Endpoint Restricted
endpoint_restricted403
This API key is allowed to authenticate, but it isn't permitted to call this specific endpoint.
What this means
The API key in this request was recognized and is active, but it's been configured with an endpoint allowlist that doesn't include the path you tried to hit. This is a 403, not a 401 — your credentials are fine. The restriction is intentional, set either by the account owner or by Asterwise for compliance reasons. The request never reached the calculation engine.
When you'll see this
- The account owner restricted the key to a subset of endpoints (e.g. a key meant only for
/v1/numerology/*was used to call/v1/astro/natal). - The key was created for a specific integration (a matrimonial app, a horoscope widget) and the calling code expanded into endpoints outside that scope.
- A development key is being used in production code that calls broader endpoints than the dev scope allowed.
Learn more about how this works
API keys can be scoped to specific endpoint prefixes during creation. The check happens on every request, before any calculation runs — so a restricted key can't accidentally rack up usage on endpoints it shouldn't touch. The restriction is per-key, not per-account: another key on the same account may have broader access.
In practice: this error usually surfaces during a migration. A team built v1 of an integration with a narrowly-scoped key, then added a new feature that calls a different endpoint family, and forgot to widen the key's allowlist. The fix is on the dashboard, not in code.
Example response
{
"success": false,
"error": "endpoint_restricted",
"message": "This API key is not permitted to call this endpoint.",
"details": [],
"retry_after": null,
"doc_url": "https://docs.asterwise.com/reference/errors/endpoint_restricted",
"request_id": "req_01HXYZABCDEFGH",
"timestamp": "2026-05-25T12:34:56Z"
}
- Sign in at asterwise.com/dashboard.
- Open the API Keys section and find the key from the failing request.
- Either widen its endpoint allowlist to include the endpoint you're calling, or create a new key with the access you need.
This error is almost always a configuration mismatch — it won't resolve itself by retrying. Surface a clear error to the calling system and fail fast rather than looping.
Python:
Production handler
- Python
- TypeScript
import httpx
class AsterwiseAccessError(Exception):
"""The key is valid but lacks permission for this endpoint."""
def call_asterwise(url, headers, payload):
response = httpx.post(url, headers=headers, json=payload, timeout=30)
if response.status_code == 403:
body = response.json()
if body.get("error") == "endpoint_restricted":
raise AsterwiseAccessError(
f"Key not permitted to call {url}. "
f"Update key scope in the Asterwise dashboard. "
f"request_id={body.get('request_id')}"
)
response.raise_for_status()
return response.json()
class AsterwiseAccessError 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 === 403) {
const body = await response.json();
if (body.error === "endpoint_restricted") {
throw new AsterwiseAccessError(
`Key not permitted to call ${url}. ` +
`Update key scope in the Asterwise dashboard. ` +
`request_id=${body.request_id}`
);
}
}
if (!response.ok) throw new Error(`HTTP ${response.status}`);
return response.json();
}
Avoid this error by
- When creating a new API key, only restrict the allowlist if you have a real reason to. Over-scoping creates this error class during normal feature growth.
- If you do scope a key, document which endpoint families it covers right next to the key name in your secrets manager.
- For multi-feature integrations, prefer one broadly-scoped key over multiple narrow ones. Fewer keys, fewer surprises.
- Add a smoke test in your deploy pipeline that calls every endpoint your app uses with the production key. Catches scope drift before customers do.