Erros & limites

Referência única — se algum comportamento divergir do descrito aqui, é bug ou doc desatualizada.

Códigos de erro

Toda resposta de erro tem o shape:

{
  "detail": "<mensagem legível>"
}

Status	Quando acontece	O que fazer
400	Sem skills relevantes pra essa intent	Reescreva o intent com mais especificidade. Se o cenário deveria ter cobertura, reporte à curadoria — vira input pro pipeline.
400	Body inválido (intent vazio, JSON malformado)	Verifique payload. Intent deve ser string não-vazia.
401	API key ausente ou inválida	Veja autenticação. Se a key foi rotacionada, atualize seu env.
403	Body referencia tenant diferente do dono da key	Defesa multi-tenant. O empresa_id no body precisa bater com o dono da API key. Em geral: não passe empresa_id explícito a menos que seja necessário.
422	Validação de schema falhou	Resposta inclui detalhe por campo. Ajuste o body.
429	Rate limit estourado	Header Retry-After indica quantos segundos esperar. Implemente backoff exponencial.
500	Erro interno	Tente novamente após alguns segundos. Se persistir, contate a curadoria com o execution_id (se houver).
503	Serviço temporariamente indisponível	Janela de manutenção ou sobrecarga. Backoff e retry. Casos raros.

60 requisições/min por API key, sliding window.
Excedeu → 429 Too Many Requests com header Retry-After: <segundos>.
Cache de respostas reduz custo: chamadas idênticas (mesmo intent + mesma seleção de skills) saem em <100ms dentro de 1h.
Caso de uso legítimo precisando de mais? Solicite aumento à curadoria — avaliamos por empresa.

Payload máximo: 256 KB no request body. Intents costumam usar <1 KB.
Timeout: 60s no compose cold (primeira chamada com intent novo). Cached: <100ms. Configure o timeout do cliente HTTP pra ≥60s.
Resposta máxima: contexto composto pode chegar a ~32 KB. Cheque limite de payload do seu connector em ferramentas low-code.

Todos os endpoints estão sob /api/v1. Mudanças retrocompatíveis (campos novos, valores opcionais) saem sem aviso.
Quebras de contrato (campo removido, semântica alterada) são anunciadas com no mínimo 60 dias de antecedência aos clientes ativos.
Quando lançarmos /api/v2, a v1 fica disponível por no mínimo 6 meses em paralelo.