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
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 Teto de custo mensal da conta atingido
AGENT_BUDGET_EXCEEDED 402 Teto de custo mensal do agente atingido
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 — o pedido estava certo, repita mais tarde. Vale para ler/escrever documentos, listar/ler fontes, busca e chunks
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 — a mensagem diz quantos apagou; re-execute (é idempotente)
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_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_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)
IMAGE_KEY_REQUIRED 400 Nenhuma chave de provedor de imagem disponível para a conta — cadastre OPENAI_API_KEY no cofre de credenciais do Console
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

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 excedido
SERVICE_UNAVAILABLE 503 Dependência indisponível
INTERNAL_ERROR 500 Erro interno (reporte o trace_id)