Erros

Envelope padrão de erro e o catálogo completo de códigos, com mensagens em português.

Todos os erros usam o mesmo envelope JSON:

{
  "error": {
    "code": "validation_error",
    "message": "Payload inválido.",
    "details": [
      { "field": "first_name", "message": "String must contain at least 1 character(s)" }
    ]
  }
}

code — identificador estável em inglês snake_case (use-o na sua lógica).
message — texto em português, pronto para log ou exibição.
details — opcional, presente em erros de validação: lista de { field, message } apontando o campo problemático.

Códigos

Autenticação e permissão

`code`	HTTP	Quando
`missing_api_key`	`401`	Header `X-API-Key` ausente.
`invalid_api_key`	`401`	Chave sem o prefixo `vnd_` ou inexistente.
`revoked_api_key`	`401`	Chave revogada ou inativa.
`insufficient_scope`	`403`	A chave não tem o escopo exigido pelo endpoint.

A mensagem de insufficient_scope é específica do recurso, por exemplo: "Esta API Key não tem permissão para criar leads." ou "Esta API Key não tem permissão de leitura para este recurso."

Requisição

`code`	HTTP	Quando
`method_not_allowed`	`405`	Método HTTP não suportado nesse endpoint.
`invalid_body`	`400`	Corpo ausente/JSON inválido no `POST /leads`.
`bad_request`	`400`	Corpo ausente/JSON inválido nos endpoints de escrita (negócios, contatos, empresas).
`validation_error`	`422`	Payload ou parâmetros de query inválidos (vem com `details`).
`invalid_cursor`	`422`	`cursor` de paginação não é um UUID válido.
`not_found`	`404`	Recurso (`:id`) não existe nesse workspace.

Regras de negócio (entrada de lead / escrita)

`code`	HTTP	Quando
`invalid_reference`	`422`	Um id referenciado (contato, empresa, etapa, etc.) não pertence ao workspace.
`pipeline_not_found`	`422`	`pipeline_id` informado não existe no workspace ou está inativo.
`no_default_pipeline`	`422`	Nenhum pipeline padrão ativo no workspace.
`stage_not_found`	`422`	`stage_id` não pertence ao pipeline ou está inativo.
`pipeline_has_no_stage`	`422`	O pipeline não tem nenhuma etapa ativa.
`owner_unresolved`	`422`	Não foi possível determinar um responsável ativo (entrada de lead).
`no_owner_available`	`422`	Não foi possível determinar um responsável ativo (escrita de negócio/contato/empresa).
`no_author_available`	`422`	Quem criou a API Key não é (mais) membro ativo do workspace (escrita de nota).

Servidor

`code`	HTTP	Quando
`internal_error`	`500`	Falha interna inesperada. Tente novamente; se persistir, contate o suporte.

Limite de requisições

Código HTTP	`code`	Quando acontece
`429`	`rate_limited`	A chave passou do limite de 120 requisições por minuto. A resposta traz o cabeçalho `Retry-After` com quantos segundos esperar — respeite-o no seu cliente.

Conta e plano

Código HTTP	`code`	Quando acontece
`403`	`workspace_suspended`	A conta está suspensa. Nenhuma chave funciona enquanto isso durar.
`403`	`feature_disabled`	O plano da conta não inclui a API pública.

Webhooks

Código HTTP	`code`	Quando acontece
`404`	`webhook_not_found`	A assinatura informada não existe (ou é de outra conta).
`422`	`invalid_event_type`	O evento pedido não está no catálogo.
`422`	`invalid_target_url`	A URL de destino foi recusada: precisa ser `https` e apontar para um endereço público.

Os erros de limite de requisições, conta e plano valem para todos os endpoints — eles acontecem antes de qualquer lógica do recurso.

Erros

Nesta página