Every error of the Qomni API has the same shape, defined once in contracts/shared/v1/components.yaml#/components/schemas/Error.
Decide by code, show message and store request_id.
Codes
| Status | code |
What to do |
|---|---|---|
401 |
api_key_missing |
The Authorization header is missing. Send Authorization: Bearer <key>. |
401 |
api_key_malformed |
The key does not have the form sk_… or its checksum does not match. Copy it again. |
401 |
api_key_invalid |
The key does not exist or was revoked. Create another one. |
401 |
api_key_wrong_product |
The key belongs to another product. Use an Agents key. |
403 |
product_not_active |
The workspace does not have Agents enabled. Enable it in Settings. |
404 |
not_found |
The route or the resource does not exist. |
404 |
host_moved |
The host is a product’s old address (agents.qomni.ai), which no longer serves pages. Use https://app.qomni.ai/{workspace}/{producto}. |
404 |
api_host_moved |
The host is the API’s old address (agents-api.qomni.ai). It does not redirect: message carries the new base URL, https://api.qomni.ai/agents/v1. Change your client’s base URL. |
404 |
unknown_api |
The first segment of the path on api.qomni.ai does not name any API. Start the path with the product and the version (/agents/v1/…). |
405 |
method_not_allowed |
The route exists, but not with that method. |
410 |
product_host_moved |
You sent a POST, PUT, PATCH or DELETE to a product’s old address (agents.qomni.ai). Those addresses only redirect a GET or HEAD to app.qomni.ai/{workspace}/{producto}; send the request there. The API does not go through those addresses: it lives at https://api.qomni.ai/agents/v1. |
421 |
wrong_cell |
The key belongs to another cell. It does not happen with a key created by the workspace. |
422 |
validation_failed |
A field is missing or invalid. Fix the fields in fields. Unknown fields are rejected too. |
429 |
rate_limited |
You exceeded the limit. Wait the seconds in Retry-After and retry. See Rate limits. |
503 |
origin_unavailable |
The cell did not respond. Nothing was done: retry with backoff. See Idempotency. |
Each operation in the reference also lists the codes specific to that
operation, for example demo_unavailable when opening a demo session.
Shape
{
"error": {
"code": "api_key_wrong_product",
"message": "This key is for another product.",
"request_id": "req_01m40n2ansfhj861etnav19mbp"
}
}| Field | Type | Description |
|---|---|---|
code |
string, required | Stable. It is the value your code decides on. |
message |
string, required | For people. It can change at any time: never compare against it. |
request_id |
string, required | Identifies the request. Include it when you write to support. |
fields |
object | Only in validation_failed: the messages for each field, by name. |
On the Agents WebSocket, an error is a message of type error with the same
{ code, message } object inside.
In your code
Read code and store request_id. For example, when you create a call without a
destination the API responds 422 with the detail of each field in fields:
if not response.ok:
error = response.json()["error"]
if error["code"] == "validation_failed":
print(error["fields"])
raise SystemExit(f"{error['code']} ({error['request_id']})")if (!response.ok) {
const { error } = await response.json();
if (error.code === "validation_failed") console.log(error.fields);
throw new Error(`${error.code} (${error.request_id})`);
}{
"error": {
"code": "validation_failed",
"message": "The to field is required.",
"request_id": "req_52abfa8dd5144eee89f62f0c653310e5",
"fields": {
"to": ["The to field is required."]
}
}
}