Saltar para o conteúdo principal
Erros seguem um único shape em toda a API: 
{
  "status": 409,
  "code": "AGENT_NAME_TAKEN",
  "message": "Agent name already exists in this workspace",
  "timestamp": "2026-05-25T14:30:12.234567Z"
}
CampoNotas
statusEcho do status HTTP. Sempre bate com o código da resposta.
codeIdentificador estável e machine-readable — seguro para usar em switch.
messageExplicação para humanos. A redação pode mudar; não dê match por padrão de texto.
timestampHorário do servidor quando o erro ocorreu. Útil para tickets de suporte.

​
Referência de status codes

StatusQuando você vai ver
200 / 201 / 204Sucesso. 201 para create, 204 para delete sem body.
400Validação falhou, JSON malformado, campos desconhecidos, paginação inválida, campo imutável tocado.
401API key ausente ou inválida. Veja Autenticação.
403Workspace sem permissão para esta operação (ex.: tentar usar feature fora do plano).
404Recurso não encontrado. Ou o ID não existe, ou pertence a outro workspace.
408Mensagem síncrona excedeu o timeout — aumente timeoutSeconds (max 300) ou use o endpoint de streaming.
409Conflito — nome duplicado, recurso já vinculado, transição de estado não permitida.
422Violação de regra de negócio — ex.: limite do plano, ciclo detectado, configuração de canal bloqueada.
429Limite de rate ou cota. Aguarde e tente de novo.
500Erro de servidor. Não deveria acontecer — abra um bug com o timestamp do body.
502Serviço upstream inacessível (a request chegou no gateway, mas um downstream — Composio, payment provider — falhou). Geralmente transiente.

​
Códigos de erro comuns

Estes são os códigos que você vai ver mais. O conjunto completo está documentado por endpoint na API Reference.

​
Autenticação

  • MISSING_API_KEY, INVALID_API_KEY_FORMAT, INVALID_API_KEY — todos 401.

​
Validação

  • VALIDATION_ERROR — 400. Body tem campos inválidos, enum errado ou propriedade desconhecida.
  • MALFORMED_JSON — 400. Body não é JSON válido.
  • IMMUTABLE_FIELD — 400. Tentou mudar um campo que não pode ser editado depois da criação (ex.: toolType).

​
Estado de recurso

  • AGENT_NOT_FOUND, CLIENT_NOT_FOUND, KNOWLEDGE_SOURCE_NOT_FOUND, etc. — 404.
  • ALREADY_LINKED, AGENT_NAME_TAKEN, SKILL_NAME_TAKEN, EXTERNAL_MCP_NAME_TAKEN — 409.

​
Regras de negócio

  • NO_DRAFT_VERSION — 409. O agente não tem draft pra modificar; publique antes ou crie um novo draft.
  • SUB_AGENT_CYCLE — 422. Linkar criaria um ciclo (A → B → A).
  • OAUTH_NOT_SUPPORTED_VIA_API — 422. Registro OAuth requer o fluxo web do Studio.
  • CHANNEL_CONFIG_NOT_ALLOWED_VIA_API — 422. Config de WhatsApp requer Meta OAuth no Studio web.
  • HTTP_TOOL_LIMIT_REACHED — 422. Workspace atingiu o limite do plano.

​
Guia de retry

StatusRetry?
400 / 404 / 409 / 422Não. Corrija a request.
401Não. Corrija a key.
408Às vezes. Aumente timeoutSeconds ou use streaming.
429Sim, com backoff exponencial. Comece em 1s, max 30s.
500 / 502Sim, com backoff exponencial. Se um 500 persistir, é bug — reporte.
Operações idempotentes (GET, DELETE) são sempre seguras para retry. Para POST / PATCH, faça retry só em falhas transientes (429, 502, erro de rede) para evitar criação dupla.