Todo erro da API da Qomni tem a mesma forma, definida uma única vez em
contracts/shared/v1/components.yaml#/components/schemas/Error. Decida por
code, mostre message e guarde request_id.
Códigos
| Status | code |
O que fazer |
|---|---|---|
401 |
api_key_missing |
Falta o header Authorization. Envie Authorization: Bearer <key>. |
401 |
api_key_malformed |
A chave não tem a forma sk_… ou seu checksum não bate. Copie-a de novo. |
401 |
api_key_invalid |
A chave não existe ou foi revogada. Crie outra. |
401 |
api_key_wrong_product |
A chave é de outro produto. Use uma chave de Agents. |
403 |
product_not_active |
O workspace não tem o Agents ativo. Ative-o em Configurações. |
404 |
not_found |
A rota ou o recurso não existem. |
404 |
host_moved |
O host é o endereço antigo de um produto (agents.qomni.ai), que já não serve páginas. Use https://app.qomni.ai/{workspace}/{producto}. |
404 |
api_host_moved |
O host é o endereço antigo da API (agents-api.qomni.ai). Ele não redireciona: message traz a nova URL base, https://api.qomni.ai/agents/v1. Troque a URL base do seu cliente. |
404 |
unknown_api |
O primeiro segmento da rota em api.qomni.ai não nomeia nenhuma API. Comece a rota pelo produto e pela versão (/agents/v1/…). |
405 |
method_not_allowed |
A rota existe, mas não com esse método. |
410 |
product_host_moved |
Você enviou um POST, PUT, PATCH ou DELETE ao endereço antigo de um produto (agents.qomni.ai). Esses endereços só redirecionam um GET ou HEAD para app.qomni.ai/{workspace}/{producto}; envie a requisição para lá. A API não passa por esses endereços: ela vive em https://api.qomni.ai/agents/v1. |
421 |
wrong_cell |
A chave é de outra célula. Não acontece com uma chave criada pelo workspace. |
422 |
validation_failed |
Um campo falta ou não é válido. Corrija os campos de fields. Campos desconhecidos também são rejeitados. |
429 |
rate_limited |
Você superou o limite. Espere os segundos de Retry-After e tente de novo. Veja Limites de uso. |
503 |
origin_unavailable |
A célula não respondeu. Nada foi feito: tente de novo com backoff. Veja Idempotência. |
Cada operação da referência lista ainda os códigos próprios dessa
operação, por exemplo demo_unavailable ao abrir uma sessão do demo.
Forma
{
"error": {
"code": "api_key_wrong_product",
"message": "This key is for another product.",
"request_id": "req_01m40n2ansfhj861etnav19mbp"
}
}| Campo | Tipo | Descrição |
|---|---|---|
code |
string, obrigatório | Estável. É o valor com que seu código decide. |
message |
string, obrigatório | Para pessoas. Pode mudar a qualquer momento: nunca compare com ele. |
request_id |
string, obrigatório | Identifica a requisição. Inclua-o quando escrever ao suporte. |
fields |
objeto | Só em validation_failed: as mensagens de cada campo, por nome. |
No WebSocket do Agents, um erro é uma mensagem do tipo error com o mesmo
objeto { code, message } dentro.
No seu código
Leia code e guarde request_id. Por exemplo, ao criar uma chamada sem
destino a API responde 422 com o detalhe de cada campo em 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."]
}
}
}