Start free →

Error codes

API keys and the person a call is for

Each code of this family: what it means, its most frequent cause, what to do and who can do it.

All error codes

api_key_invalid

What it means
The Azoth API key sent with the call matches no active key.
Most frequent cause
A revoked or expired key, or a key copied with a character missing.
What to do
This Azoth API key is not valid (revoked, expired or mistyped). Create a new one in Settings › Access.
Who can do it
An owner or admin of the workspace · Open the screen

api_key_missing

What it means
The call carries no Azoth API key.
Most frequent cause
The Authorization or X-Azoth-API-Key header is missing, often because an environment variable is not set.
What to do
No Azoth API key was sent. Paste a key from Settings › Access.
Who can do it
The developer of the calling code

api_key_scope_denied

What it means
The key is valid, but it is limited — to scopes (the parts of the API it may call), to connectors or to environments — and this call falls outside those limits. At ingest, the answer’s dimension says which limit refused it: connector or environment.
Most frequent cause
A key created for one use, such as ingest or reading, called another part of the API — or sent events for a connector or an environment the key was not created for.
What to do
This API key is limited to some scopes, connectors or environments, and this call falls outside them. Create a key that covers it, or one with no such limits (unrestricted).
Who can do it
An owner or admin of the workspace · Open the screen

api_key_name_taken

What it means
A live key of the workspace already has the name asked for: two live keys of one workspace never share a name.
Most frequent cause
A key created earlier with this name and never revoked — an expired key keeps its name until it is revoked.
What to do
A live key of this workspace already has this name. Choose another name, or revoke that key in Settings › Access first.
Who can do it
An owner or admin of the workspace · Open the screen

api_key_role_denied

What it means
The key is valid, but its role — read, write or admin — is below what this route needs: a read key cannot call a route that writes, and an export of the workspace’s settings needs an admin key.
Most frequent cause
A key created read-only, used by code that sends data or makes changes — or a key of another role than the one the integration was set up with.
What to do
This API key’s role does not allow this call: a read key cannot write, and some exports need an admin key. Create a key with the needed role in Settings › Access.
Who can do it
An owner or admin of the workspace · Open the screen

ip_not_allowed

What it means
The key is valid, but the call came from an address outside the workspace’s IP allowlist: the workspace accepts its API keys only from the addresses it lists.
Most frequent cause
A new server, a cloud function or a network whose outbound address is not listed yet — or a proxy that changes the address the call comes from.
What to do
This call came from an address outside the workspace’s IP allowlist. Call from a listed address, or ask an owner or admin to add this one.
Who can do it
An owner or admin of the workspace

on_behalf_of_not_allowed

What it means
This call was blocked: its API key may not name the person it is for.
Most frequent cause
Only a service key an owner or administrator allowed to may send X-Azoth-On-Behalf-Of. A personal key always speaks for its owner.
What to do
Send the call without that header, or ask an owner or administrator for a service key allowed to name people (Settings › Access).
Who can do it
An owner or admin of the workspace · Open the screen

human_identity_required

What it means
This call was blocked: it does not name the person it is for.
Most frequent cause
This workspace requires every call to be attributed to a person, so that each decision can show who made it.
What to do
Use your personal API key, or send X-Azoth-On-Behalf-Of (the person’s SCIM id or e-mail) with a service key allowed to name people.
Who can do it
The developer of the calling code · Open the screen

identity_unavailable

What it means
This call was blocked: the person it is for could not be checked.
Most frequent cause
Azoth could not read the key or the workspace’s attribution rules, and does not serve a call it cannot attribute when attribution is required.
What to do
Try again in a moment.
Who can do it
Azoth, or the operator of this deployment

invalid_on_behalf_of

What it means
The X-Azoth-On-Behalf-Of header is not an identifier of a person Azoth can read.
Most frequent cause
The header is empty, longer than 256 characters, or holds characters outside visible ASCII.
What to do
X-Azoth-On-Behalf-Of must be 1 to 256 visible ASCII characters: send the person's SCIM id or e-mail.
Who can do it
The developer of the calling code

key_not_bound_to_agent

What it means
The MCP gateway answers only an API key bound to one agent — the agent whose mandate decides what it may call — and this key is bound to none.
Most frequent cause
A workspace key used instead of the key made for an agent in the MCP tools tab, or an agent key that was unbound since.
What to do
This API key is bound to no agent. Create a key for the agent in the MCP tools tab of Mandates, and give that key to the MCP client.
Who can do it
An owner or admin of the workspace · Open the screen

invalid_key_identity

What it means
A personal key always speaks for its owner: it cannot also name other people.
Most frequent cause
A personal key created with the option to name people turned on.
What to do
To name people, create a service key with that option; a personal key is created without it.
Who can do it
An owner or admin of the workspace · Open the screen