Erros

O envelope de erro e o significado de cada código retornado pela API.

Todos os erros usam o mesmo envelope:

{ "errors": [ { "field": "...", "detail": "..." } ] }

400 · Requisição inválida

Parâmetros de query inválidos, JSON malformado ou corpo acima de 512 KB. Vários parâmetros inválidos são relatados juntos:

{
  "errors": [
    { "field": "status", "detail": "Valor inválido. Valores permitidos: ongoing, won, lost" },
    { "field": "created_at__gte", "detail": "Data inválida. Use o formato ISO 8601" },
    { "field": "per_page", "detail": "Informe um número inteiro maior que zero" }
  ]
}

401 · Não autenticado

Sempre o mesmo corpo, qualquer que seja o problema com a credencial:

{ "errors": [{ "detail": "Chave de API inválida" }] }

Veja Autenticação.

403 · Sem permissão

{ "errors": [{ "detail": "A chave de API não possui permissão para esta operação" }] }

Veja Escopos e permissões.

404 · Não encontrado

Rota desconhecida ou recurso inexistente. Ids de outra conta também retornam 404, indistinguíveis de ids inexistentes.

{ "errors": [{ "detail": "Negociação não encontrada" }] }

422 · Validação do corpo

Todos os problemas do corpo em uma única resposta:

{
  "errors": [
    { "field": "phone", "detail": "Telefone inválido. Informe de 10 a 15 dígitos, incluindo DDI e DDD" },
    { "field": "custom_fields.erp", "detail": "Campo personalizado não encontrado" }
  ]
}

429 · Limite excedido

Veja Limites de requisição.

500 · Erro interno

{ "errors": [{ "detail": "Erro interno do servidor" }] }

Nenhum detalhe interno é exposto. Se o erro persistir, entre em contato com o suporte informando o horário e a rota chamada.