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).

Servidor

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

Webhooks (em breve) acrescentam os códigos webhook_not_found, invalid_event_type e invalid_target_url. Veja Webhooks.