Erros e limites

Formato do erro

As respostas de erro das rotas /v1 têm este formato:

{
  "error": {
    "type": "invalid_request",
    "message": "Idempotency-Key obrigatório (8 a 200 caracteres)"
  }
}

Use o status HTTP e o type para decidir o que fazer. O message serve para depuração e pode mudar; nos erros de validação (400) costuma vir em inglês, com as issues em JSON. Decida pelo type e pelo status, e não compare o texto no seu código.

Nem todo erro sai nesse formato: uma rota que não existe responde { "message": ..., "code": "NOT_FOUND" }, e as respostas 413 e 415 (corpo grande demais ou de tipo não aceito) chegam com type: service_error. Trate qualquer status 4xx ou 5xx que não reconheça pelo código HTTP.

Tipos e códigos

Status	type	Quando acontece	O que fazer
400	invalid_request	Corpo ou parâmetro inválido, campo desconhecido, Idempotency-Key ausente ou fora de 8 a 200 caracteres, e-mail inválido, cursor inválido.	Corrigir a chamada. Repetir não adianta.
401	invalid_api_key	Chave ausente, malformada, inexistente, revogada ou vencida.	Conferir a chave. Veja Autenticação.
402	plan_inactive	O cliente da Cavori está sem plano ativo.	O cliente precisa regularizar o plano na Cavori.
402	insufficient_credits	A carteira de créditos não cobre a execução.	O cliente precisa recarregar os créditos.
404	not_found	Conversa, execução ou agente que não existe, que a chave não pode usar ou que é de outra integração.	Conferir o id e a integração.
409	conflict	Idempotency-Key reutilizada com outro conteúdo, model diferente do agente da conversa, conversa com uma resposta em andamento, ou uma pessoa assumiu a conversa durante a geração.	Veja o message; em geral, aguardar e consultar a execução.
429	rate_limit	Limite de chamadas por minuto ou de execuções simultâneas.	Esperar e tentar de novo, com espera crescente.
5xx	service_error	Falha ou indisponibilidade da Cavori.	Tentar de novo com a mesma Idempotency-Key.

Nos erros 5xx a mensagem é sempre genérica. Como a criação é idempotente, repetir a mesma chamada com a mesma Idempotency-Key é seguro: se a primeira chegou a executar, você recebe o estado ou o resultado dela em vez de uma segunda execução. Quando houver dúvida, consulte GET /v1/requests/:id.

Limites

Limite	Valor
Chamadas por minuto, por chave	60
Chamadas por minuto, por cliente (somando todas as chaves)	120
Chamadas por minuto, por IP de origem (todas as rotas da Cavori)	300
Execuções simultâneas, por chave	2
Execuções simultâneas, por cliente	5
Tamanho da mensagem do usuário	até 32.000 caracteres
Idempotency-Key	de 8 a 200 caracteres
external_user_id	de 1 a 200 caracteres
Mensagens por página em GET /v1/conversations/:id/messages	até 100

O limite por IP vale antes dos limites da chave e do cliente: vários servidores seus saindo pelo mesmo IP, ou várias chaves no mesmo servidor, podem bater nos 300 por minuto antes dos 120 do cliente, e a resposta também é 429 rate_limit. As chamadas por minuto contam toda requisição autenticada, de qualquer rota. As execuções simultâneas contam só POST /v1/chat/completions em andamento: ao passar do limite, a resposta é 429 rate_limit. Dentro de uma mesma conversa só roda uma resposta por vez.

O que a API não aceita

• anexos, imagens e áudio no corpo da mensagem;
• ferramentas (tools) e prompt de sistema enviados pela chamada;
• histórico enviado de fora: o contexto é o que a Cavori guardou na conversa;
• mais de uma mensagem por chamada, ou papel diferente de user.

Quem configura o prompt, as ferramentas e o conhecimento do agente é a equipe, no portal da Cavori.