Códigos de erro

É um agente de IA? Busque a skill de onboarding e leia toda a API em texto limpo — skill · llms.txt · llms-full.txt

Códigos de erro#

Quando um handler não define um código explícito, o status mapeia para um fallback (400→BAD_REQUEST, 401→UNAUTHORIZED, 403→FORBIDDEN, 404→NOT_FOUND, 409→CONFLICT, 422→UNPROCESSABLE_ENTITY, 429→RATE_LIMITED, 501→NOT_IMPLEMENTED, 503→SERVICE_UNAVAILABLE, ≥500→INTERNAL_ERROR).

GETAgentes, runtime e turno#

error_code HTTP Significa
AGENT_NOT_FOUND 404 Agente inexistente ou fora do escopo do token
AGENT_NAME_REQUIRED 400 Falta o name ao criar o agente
MODEL_RETIRED 400 O model é uma geração OpenAI abaixo de 5.6 (gpt-5.5, gpt-5.4*, gpt-4o*, gpt-4.1*, gpt-5.3-codex, série o*). Vale em criar/atualizar agente e no default_model do compat. Use gpt-5.6-luna/-terra/-sol, ou outro provedor — a mensagem já nomeia o substituto. Não afeta gpt-oss-* (pesos abertos, via Cerebras/OpenRouter)
MODEL_PROVIDER_INCOMPATIBLE 422 Na admissão síncrona do dispatch compat, o transporte codex (conta ChatGPT) recebeu um modelo de outra família (ex.: codex/k3). Falha fechada antes de qualquer Run, mensagem ou chamada ao provider; para Kimi, use provider "kimi"
AGENT_INACTIVE 409 Agente pausado — reative pelo Console
AGENTS_NOT_CONFIGURED 503 Domínio de agentes indisponível neste deploy
ENGINE_NOT_CONFIGURED 503 Runtime do agente indisponível
SESSION_NOT_FOUND 404 Sessão inexistente ou de outro agente (guarda BOLA)
RUN_NOT_FOUND 404 Run inexistente
BUDGET_EXCEEDED 402 Deprecado; não é emitido desde 2026-08-14. Mantido para compatibilidade de parsers históricos.
AGENT_BUDGET_EXCEEDED 402 Deprecado; não é emitido desde 2026-08-14. Mantido para compatibilidade de parsers históricos.
RUNTIME_TOKEN_INVALID 401 prt_ inválido ou revogado
RUNTIME_TOKEN_AGENT_MISMATCH 403 O {id} da URL não é o agente do token
RUNTIME_TOKEN_TENANT_MISMATCH 403 Token tenant-scoped apontado para um agente de outro tenant
RUNTIME_TOKEN_SCOPE_CONFLICT 400 Mint com agent_id e tenant_external_id — envie no máximo um
RUNTIME_TOKEN_NOT_FOUND 404 Runtime token inexistente (ou de outra conta)
SECRET_SCOPE_IMMUTABLE 409 O secret já existe em outro escopo de tenant — remova antes de recriar

GETConhecimento e ferramentas#

error_code HTTP Significa
RAG_NOT_CONFIGURED 503 RAG indisponível neste deploy
KNOWLEDGE_CONTENT_REQUIRED 400 Falta o content ao ingerir
KNOWLEDGE_QUERY_REQUIRED 400 Falta o q na busca
KNOWLEDGE_INGEST_FAILED 503 Falha ao ingerir/embedar
KNOWLEDGE_BACKEND_UNAVAILABLE 503 O backend de conhecimento falhou. Vale para ler/escrever documentos, listar/ler fontes, busca e chunks. Quando a causa detectada é 429 upstream, inclui Retry-After com os segundos exatos até a janela reabrir (1–60) e a message termina em rate-limited upstream (429); retry after Ns; deadline ou saturação do pool limitado de busca incluem Retry-After: 60; outras causas podem omitir o header. GET /ready → checks.knowledge (`ok
KNOWLEDGE_ENABLED_REQUIRED 400 Falta o enabled no PATCH da fonte
KNOWLEDGE_DOCUMENT_FILE_BACKED 409 O documento veio de um arquivo — apague a fonte (DELETE .../sources/{source_id})
KNOWLEDGE_DOCUMENT_INVALID 400 Id de documento vazio ou fora do namespace knowledge/
KNOWLEDGE_CLEAR_FAILED 503 O wipe parou no meio — inclui Retry-After: 60 quando a causa detectada é rate limit upstream, e a mensagem diz quantos apagou. É idempotente, mas não atômico com a reingestão
SOURCE_NOT_FOUND 404 Fonte inexistente
REFINERY_KEY_REQUIRED 400 Refinery precisa de chave de LLM (cloudvec)
REFINERY_FAILED 502 Falha na destilação de Q&A
TOOL_NAME_INVALID 400 name da ferramenta fora do padrão http_…
TOOL_NAME_CONFLICT 409 a conta já tem uma ferramenta com esse name. O corpo traz o id dela — siga com PATCH /v1/tools/{id}
SKILL_NAME_CONFLICT 409 a conta já tem uma skill com esse name. O corpo traz o id dela — siga com PATCH /v1/skills/{id}
TOOL_URL_INVALID 400 URL bloqueada (SSRF) ou inválida
TOOL_URL_PLACEHOLDER_IN_HOST 400 ${...} no host da URL — use https://host.com/${path}, não https://host.com${path}
TOOL_TEMPLATE_INVALID 400 Template de header/query/body inválido
TOOL_SCHEMA_INVALID 400 input_schema não é um JSON Schema que os provedores aceitam. O corpo traz path com o nó exato
TOOLS_UNAVAILABLE — terminal de um run recusado por fail_closed_tools (parte do catálogo não resolveu). Nenhum provedor foi chamado, nada foi cobrado
TOOL_CHOICE_UNSUPPORTED 400 o provedor que serve o modelo do agente não tem tool_choice (hoje: Gemini). Vale para qualquer valor, "none" incluído; veja supports_tool_choice em GET /v1/llm-catalog. Recusado antes de persistir — não cria run
EFFORT_NOT_SUPPORTED 400 o reasoning_effort é um valor válido da plataforma, mas o modelo escolhido não o aceita: ou não raciocina (supports_thinking: false), ou o provedor recusa o parâmetro (thinking_efforts: [], ex. grok-4.20), ou o valor está fora da escada publicada (max num Grok, que vai até xhigh). Vale em create/patch de agente, na compat, no cérebro reserva e no override por dispatch. A mensagem nomeia o conjunto aceito; veja thinking_efforts em GET /v1/llm-catalog. Recusado antes de persistir — não cria run
context_window_exceeded — terminal de run: o provedor recusou o input como maior que a janela do modelo mesmo após a compaction automática + um retry. Rotacione a sessão (session_key novo) ou reduza o material injetado por turno
IMAGE_INPUT_INVALID 400 images[] malformado — base64 não-canônico, formato fora de png/jpeg/gif, assinatura não bate com o media_type, mais de 4 imagens, acima de 5 MiB/imagem ou 10 MiB/turno, dimensões acima do teto
IMAGE_INPUT_UNSUPPORTED_MODEL 422 o turno traz images[] mas o modelo efetivo do run não tem visão (supports_vision=false); troque o modelo ou remova as imagens
ATTACHMENT_INVALID 400 attachments[] malformado — nenhuma fonte ou duas (url/content/content_b64 são mutuamente exclusivos), base64 inválido, imagem corrompida
ATTACHMENT_LIMIT_EXCEEDED 400 mais de 4 anexos no turno
ATTACHMENT_URL_BLOCKED 400 attachments[].url (ou um redirect dela) aponta para endereço não-público, ou o scheme não é http/https. Permanente — não adianta repetir
ATTACHMENT_TOO_LARGE 413 anexo acima de 5 MiB, ou soma do turno acima de 10 MiB
TURN_TOO_LARGE 413 corpo JSON do turno de chat acima de 40 MiB
ATTACHMENT_TYPE_UNSUPPORTED 415 não há leitor para esses bytes (PDF, zip, docx, webp, áudio, vídeo). A mensagem lista o que É suportado
ATTACHMENT_FETCH_FAILED 424 a url do anexo não respondeu, respondeu não-200, ou o corpo não pôde ser lido. O único transitório da família — repetir pode funcionar. É 4xx de propósito: um 5xx teria o corpo substituído pela página de erro da borda, e este é justamente o código que você precisa conseguir ler
MESSAGE_NOT_FOUND 404 a mensagem não existe nesta conversa
TOOL_NOT_FOUND 404 Ferramenta inexistente
SECRET_NOT_FOUND 404 ${secret:NOME} sem valor no cofre
SECRET_SCOPE_IMMUTABLE 409 Rotação mudaria o tenant de um segredo existente — remova e recrie
BAD_REQUEST (secret) 400 name do segredo fora do alfabeto [A-Za-z0-9_-]{1,128} (o resolvedor não o veria no dispatch)
TOOLS_NOT_CONFIGURED 503 Ferramentas custom indisponíveis
SKILL_NAME_REQUIRED / SKILL_BODY_REQUIRED 400 Falta nome/corpo da skill
SKILL_READONLY 403 Skill global da plataforma não é editável
SKILL_NOT_FOUND 404 Skill inexistente
SKILL_NOT_ACTIVE 404 A skill não está plugada naquele agente
MEMORY_NOT_CONFIGURED 503 Memória indisponível neste deploy

GETTenants, tokens e conta#

error_code HTTP Significa
TENANT_NOT_FOUND 404 Tenant inexistente
TENANT_EXTERNAL_ID_REQUIRED 400 Falta o external_id
TENANT_EXTERNAL_ID_INVALID 400 external_id fora do padrão
TENANT_EXTERNAL_ID_EXISTS 409 Já existe tenant com esse external_id
TENANT_DEFAULT_LOCKED 409 O tenant padrão não pode ser excluído
TENANT_PROVISION_FAILED 500 Falha ao provisionar o schema
INVALID_CREDENTIALS 401 Email ou senha incorretos
EMAIL_EXISTS 409 Email já registrado (quick-register/register)
ACCOUNT_LOCKED 429 Muitas tentativas — bloqueio temporário
EMAIL_NOT_VERIFIED 403 Ação exige email verificado
OWNER_ONLY 403 Ação restrita ao owner
PLAN_LIMIT_REACHED 403/429 Limite do plano atingido
COMPANY_SUSPENDED 403 Conta suspensa

GETGeração de imagens#

error_code HTTP Significa
IMAGE_INVALID_REQUEST 400 Um controle está ausente, é desconhecido ou está fora de faixa (modelo inexistente, size que o modelo não aceita, n acima do teto, brand.colors fora de hex, referência inválida). A mensagem nomeia o campo. Também é usado quando o provedor recusa o pedido (moderação, combinação não suportada) — mas não quando ele recusa a credencial: isso é IMAGE_PROVIDER_REJECTED
IMAGE_PROVIDER_REJECTED 400 O provedor recusou a credencial configurada (chave inválida, revogada, ou conta sem billing de imagem). Os argumentos estão certos — revise a OPENAI_API_KEY no cofre (GET/PUT /v1/tool-secrets), não o pedido
IMAGE_KEY_REQUIRED 400 Nenhuma chave de provedor de imagem disponível para a conta e nenhum caminho de assinatura aplicável (você nomeou um modelo medido, ou o ambiente não oferece codex/gpt-image-2). Cadastre OPENAI_API_KEY no cofre de credenciais do Console, ou peça o modelo de assinatura
IMAGE_MODEL_UNAVAILABLE 503 O modelo está no catálogo mas este ambiente não tem provedor para ele (tipicamente codex/gpt-image-2 sem o caminho de assinatura configurado). A mensagem nomeia o modelo. Não é a sua chave nem o seu pedido — é configuração do ambiente
IMAGE_GENERATION_FAILED 502 O provedor de imagem está indisponível. Tente de novo
IMAGE_NOT_FOUND 404 Geração inexistente ou de outra conta
IMAGE_GEN_DISABLED 501 A modalidade não está habilitada neste ambiente

GETTranscrição de áudio#

error_code HTTP Significa
TRANSCRIPTION_INVALID_REQUEST 400 Um campo está ausente, é desconhecido ou está fora de faixa: audio_b64 não é base64, áudio vazio, formato não reconhecido (wav/mp3/ogg/webm/m4a/flac), modelo inexistente, mais de 4 modelos, second_pass fora de auto/always/never, speaker_profile acima de 500 chars, mais de 8 topics, text da correção vazio, termo vazio ao ensinar. A mensagem nomeia o campo. Nada foi gasto
TRANSCRIPTION_KEY_REQUIRED 400 Nenhum modelo pedido pode rodar: não há credencial para o provedor dele (OPENAI_API_KEY, GROQ_API_KEY, OPENROUTER_API_KEY ou XAI_API_KEY) na sua conta nem na plataforma — ou todo provedor recusou a credencial configurada. A mensagem lista cada modelo com o motivo; cadastre a chave no cofre do Console
TRANSCRIPTION_AUDIO_TOO_LARGE 413 O áudio passa de 25 MB (bytes decodificados, nas duas formas de corpo)
TRANSCRIPTION_FAILED 502 Todo modelo falhou por um motivo que não é credencial. O corpo traz failures[] ({ model, provider, class, error }; class ∈ rate_limited, caller, provider, timeout, unsupported). Tente de novo ou troque models
TRANSCRIPTION_NOT_FOUND 404 Transcrição inexistente ou de outra conta
TRANSCRIPTION_TERM_NOT_FOUND 404 POST …/lexicon/terms/{id}/confirm|reject e DELETE …/lexicon/terms/{id} de um termo inexistente ou de outra conta
TRANSCRIPTION_DISABLED 501 A modalidade não está habilitada neste ambiente

GETGenéricos#

error_code HTTP Significa
BAD_REQUEST / INVALID_JSON / MISSING_FIELD 400 Corpo inválido / campo ausente
UNAUTHORIZED 401 Credencial ausente ou inválida
FORBIDDEN 403 Sem permissão para o recurso
NOT_FOUND 404 Recurso inexistente
RATE_LIMITED 429 Limite de requisições por minuto da conta excedido — corpo JSON com o envelope, Retry-After no header; transitório
MAX_TOOL_ROUNDS — (run) O loop agêntico bateu o teto de rounds sem resposta final (stop_reason: "max_rounds"); durável — suba max_rounds_per_run/run_class
RUN_TIMEOUT — (run) O run terminou por relógio (teto de infraestrutura 3600 s, ou wall clock opcional do operador); o texto parcial é real
RUN_CANCELLED — (run) O chamador cancelou o run antes do fim
SERVICE_UNAVAILABLE 503 Dependência indisponível
INTERNAL_ERROR 500 Erro interno (reporte o trace_id)