Erros & Códigos

Esta é a fonte única de verdade sobre erros da API pública. Todos os endpoints seguem o mesmo envelope e o mesmo conjunto de códigos de status descritos aqui. As páginas de recurso não repetem esta informação — elas apenas referenciam esta página.

Envelope de erro

Toda resposta de falha tem data: null, e em falhas de validação também errors:

{
  "message": "string",
  "data": null,
  "errors": {
    "campo": ["mensagem"]
  }
}

message: descrição legível do erro, em português, sempre presente.
data: sempre null numa resposta de erro.
errors: mapa de campo para lista de mensagens. Aparece apenas em falhas de validação (422).

Códigos de status HTTP

Status	Significado	Quando ocorre
`401` Unauthorized	Não autenticado	Segredo da API Key ausente, malformado, revogado, expirado, ou IP fora da allowlist da chave.
`403` Forbidden	Sem permissão	A chave não tem o escopo necessário para a operação (ver Escopos & Permissões).
`404` Not Found	Não encontrado	Recurso inexistente ou pertencente a outra empresa. Nunca `403` por esse motivo — ver Multi-tenancy.
`422` Unprocessable	Falha de validação	Corpo sintaticamente válido, mas com campos que não passam nas regras, ou uma regra de negócio (ex.: etapa que não pertence ao funil do negócio). Inclui `errors` quando é validação de campo.
`429` Too Many Requests	Limite excedido	Mais de 120 requisições por minuto com a mesma chave. Detalhes em Rate limiting.

Exemplos reais por status

401 — Não autenticado

{
  "message": "Não autenticado.",
  "data": null
}

403 — Sem escopo

{
  "message": "A chave não tem o escopo necessário.",
  "data": null
}

404 — Não encontrado

{
  "message": "Recurso não encontrado.",
  "data": null
}

422 — Validação de campo

{
  "message": "Os dados informados são inválidos.",
  "data": null,
  "errors": {
    "contact_name": ["O campo contact_name é obrigatório."],
    "stage_id": ["O campo stage_id selecionado é inválido."]
  }
}

422 — Regra de negócio

Algumas respostas 422 não trazem errors por campo — são uma regra de negócio, não um formato de dado inválido:

{
  "message": "A etapa selecionada não pertence ao funil do negócio.",
  "data": null
}

{
  "message": "O funil deste negócio não tem um status padrão do tipo \"ganho\" — informe \"status\" explicitamente.",
  "data": null
}

429 — Limite excedido

{
  "message": "Limite de chamadas da API excedido. Tente novamente mais tarde.",
  "data": null
}

Os headers de controle (X-RateLimit-*, Retry-After) são descritos em Rate limiting.

Boas práticas de tratamento

Trate o status HTTP como fonte primária de decisão; use message para exibição e errors para mapear falhas por campo quando presente.
O campo errors só está presente em parte das respostas 422 — quando é uma regra de negócio, o 422 vem só com message. Não assuma que errors sempre existe nesse status.
Para 429, consulte os headers de controle descritos em Rate limiting.
Para 401, confira o segredo, o ambiente (live/test) e a validade da chave em Autenticação.