Erros, limites e convenções

Formato de erros, limites por plano, idempotência, paginação, versionamento e consumo.

Formato dos erros

Todo erro devolve um código HTTP e um corpo neste formato:

json

{
  "error": {
    "type": "invalid_request",
    "code": "missing_param",
    "message": "O campo 'agent_id' é obrigatório.",
    "param": "agent_id",
    "request_id": "req_8q1m2z"
  }
}

Envie o request_id ao suporte quando precisar de ajuda. Ele também volta no cabeçalho Nevox-Request-Id de toda resposta.

HTTP	`type`	Quando
400	`invalid_request`	Parâmetro faltando, formato errado ou valor inválido
401	`authentication_error`	Chave ausente, inválida ou revogada
403	`permission_error`	Falta escopo, plano não inclui a API ou domínio não permitido
404	`not_found`	O recurso não existe ou é de outra conta
409	`conflict`	Conflito de estado (ex.: enviar mensagem numa conversa encerrada) ou idempotência reutilizada com outro corpo
413	`invalid_request`	Corpo ou arquivo grande demais
422	`invalid_request`	Dados válidos no formato, mas recusados pela regra (ex.: URL de ação privada)
429	`rate_limit_error`	Limite de requisições ou franquia do mês atingidos
500, 502, 503	`api_error`	Problema do nosso lado. Tente de novo com espera crescente.

Códigos mais comuns

`code`	Significado
`missing_param`, `invalid_param`	Problema num campo, indicado em `param`
`invalid_api_key`, `revoked_api_key`	Chave inválida ou revogada
`insufficient_scope`	A chave não tem o escopo necessário
`plan_required`	A API exige o plano Pro - 3 Agentes ou Ultimate - 5 Agentes, com a assinatura ativa
`feature_not_in_plan`	Recurso só do Ultimate - 5 Agentes (ex.: exportação)
`origin_not_allowed`	Chave pública usada num domínio fora da lista
`session_token_expired`	O token de sessão do widget expirou
`conversation_closed`	A conversa já foi encerrada
`idempotency_key_reused`	A mesma chave de idempotência com outro corpo
`rate_limited`	Muitas requisições por minuto
`monthly_quota_exceeded`	Franquia do mês atingida (conversas, `/ask` ou eventos)

Limites de requisição

	Pro - 3 Agentes	Ultimate - 5 Agentes	Chaves de teste
Requisições por minuto, por conta	60	300	20
Mensagens por minuto, por conversa	20	20	20
Eventos de rastreamento pelo navegador	Sem limite prático	Sem limite prático	—

Toda resposta traz:

texto

RateLimit-Limit: 60
RateLimit-Remaining: 57
RateLimit-Reset: 41

RateLimit-Reset é o número de segundos até o limite renovar. Ao receber 429, espere o tempo indicado no cabeçalho Retry-After.

Franquias mensais

As conversas pela API e pelo widget contam na mesma franquia de conversas do plano (Pro - 3 Agentes: 900; Ultimate - 5 Agentes: 1.600). O /ask e os eventos pelo servidor têm franquias próprias. Veja a tabela de planos.

Você recebe um email quando atinge 80% e 100% de qualquer franquia.

Uso

GET /v1/usage (qualquer chave válida)

json

{
  "plan": "pro",
  "period": { "start": "2026-11-01", "end": "2026-11-30" },
  "conversations": { "used": 812, "limit": 2000 },
  "ask": { "used": 112, "limit": 1000 },
  "server_events": { "used": 2310, "limit": 10000 },
  "api_keys": { "used": 2, "limit": 3 },
  "webhook_endpoints": { "used": 1, "limit": 3 }
}

Idempotência

Para repetir um POST com segurança (ex.: depois de um timeout), envie o cabeçalho Idempotency-Key com um valor único, como um UUID:

texto

Idempotency-Key: 6c1f0e2a-1b8e-4f0e-9d0a-1d2c3b4a5e6f

Por 24 horas, a mesma chave devolve a mesma resposta sem repetir a operação. Usar a mesma chave com um corpo diferente devolve 409 idempotency_key_reused.

Paginação

Listas usam cursor:

bash

curl "https://api.nevox.ai/v1/conversations?limit=50&cursor=eyJpZCI6..." \
  -H "Authorization: Bearer $NEVOX_API_KEY"

json

{
  "data": [ ... ],
  "has_more": true,
  "next_cursor": "eyJpZCI6ImNvbnZfN..."
}

limit vai de 1 a 100 (padrão 20). Quando has_more for false, você chegou ao fim.

Versionamento

A versão principal fica no caminho (/v1). Mudanças que podem quebrar integrações só entram numa nova versão principal, com aviso de pelo menos 6 meses.

Na /v1 podemos, sem aviso: adicionar endpoints, adicionar campos nas respostas, adicionar valores novos em campos de lista (como novos tipos de evento) e adicionar parâmetros opcionais. Escreva sua integração para ignorar campos que ela não conhece.

Todas as mudanças ficam no changelog.

IDs

Prefixo	Recurso
`agt_`	Agente
`conv_`	Conversa
`msg_`	Mensagem
`ctc_`	Contato
`kn_`	Item de conhecimento
`svc_`	Serviço
`act_` / `inv_`	Ação / chamada de ação
`whk_` / `evt_`	Webhook / evento de webhook
`fb_` / `sug_`	Feedback / sugestão de aprendizado
`vis_` / `ses_`	Visitante / sessão
`exp_`	Exportação
`req_`	Requisição