Erros e códigos

📘
Um formato só
Toda resposta de erro tem o mesmo formato: statusCode, error, message e, na maioria, um code estável entre versões. Decida pelo código, não pela mensagem em português.

{
  "statusCode": 422,
  "code": "UNKNOWN_NAME",
  "error": "Unprocessable Entity",
  "message": "..."
}

O 409 acrescenta duplicates. Um 5xx nunca carrega detalhe interno.

📋 Referência de códigos

status	code	O que significa	Como resolver
`400`	`FST_ERR_VALIDATION`	Corpo inválido: campo obrigatório faltando, tipo errado ou campo desconhecido.	Leia a `message` (ex.: `body/ Unrecognized key: ...`) e corrija o campo.
`401`	(sem code)	Credencial inválida, revogada ou expirada.	Gere/gire a chave em Configurações > Chaves de API.
`403`	`SCOPE_DENIED`	A chave é válida, mas não tem o escopo desta rota.	A `message` diz qual escopo falta; crie uma chave com esse escopo.
`403`	`MODULE_NOT_ENABLED`	O convênio não contratou o módulo da rota (ex.: contratos exigem o Administrativo).	Fale com o convênio; não é problema da chave.
`403`	`FORBIDDEN`	O registro existe, mas a API não o altera (ex.: atividade vinda de agenda externa).	A alteração é feita pela imobiliária.
`404`	`NOT_FOUND`	O registro do caminho (`{id}`) não existe.	Confira o id; use a busca para localizar.
`409`	`DUPLICATE_ADDRESS`	Já existe imóvel com esse endereço.	A resposta traz `duplicates`; altere o existente em vez de criar outro.
`422`	`UNKNOWN_NAME`	Tipo, bairro, cidade, unidade, motivo ou tipo de atividade que não existe no convênio.	Consulte o catálogo (`/schema/...`, `/schema/support`) e use o nome exato.
`422`	`UNKNOWN_REFERENCE`	Um id de vínculo (`assigneeId`, `propertyId`, `personId`...) não existe no convênio.	O campo vem em `field`; confira o id.
`422`	`VALIDATION_ERROR`	Combinação de campos inválida (ex.: visita virtual sem `canalVirtual`, prazo no passado).	Leia a `message` e `issues`.
`422`	`AMBIGUOUS_NAME`	O nome casa com mais de um cadastro (ex.: dois bairros homônimos).	A `message` traz os ids; o convênio precisa renomear um deles. Nunca escolhemos por você.
`422`	`UNKNOWN_CHARACTERISTIC`	Característica inexistente, ou que não pertence ao tipo de imóvel informado.	Veja `/schema/properties?propertyType=<nome>` e use uma característica válida daquele tipo.
`422`	`AMBIGUOUS_CHARACTERISTIC`	Duas características com o mesmo nome.	A `message` traz os ids; ajuste o cadastro.
`422`	`DUPLICATE_CHARACTERISTIC`	Duas chaves do seu objeto `characteristics` apontam para a mesma característica (`"Quartos"` e `"quartos"`).	Deixe uma só.
`422`	`INVALID_CHARACTERISTIC_VALUE`	Valor incompatível com o tipo do dado: texto em campo numérico, decimal em inteiro, opção fora da lista de um `select`, data inexistente.	Veja o tipo de dado no catálogo e ajuste o valor.
`422`	`TAG_INACTIVE` / `TAG_OBJECT_MISMATCH`	Etiqueta inativa, ou que não serve para aquele tipo de registro.	Use uma etiqueta ativa do objeto certo (`GET /tags`).
`422`	`PHOTO_*`	Foto por URL recusada: URL inválida ou fora da internet pública, download falhou, arquivo grande demais, tipo não aceito ou limite de fotos atingido.	O sufixo diz qual; a descrição de `POST /properties/{id}/photos` lista todos.
`429`	(sem code)	Limite excedido (120/min ou 1.000/hora).	Espere o `Retry-After` e reenvie. Um `429` significa que não foi processado.
`500`	`INTERNAL_ERROR`	Falha nossa. A mensagem é genérica de propósito.	Guarde o horário da chamada e acione o suporte.

🤝 Códigos do fluxo comercial

As ações de atendimento, visita, proposta e atividade devolvem estes códigos:

status	code	O que significa
`409`	`ATENDIMENTO_INVALID_STATE`	O atendimento não está em andamento (ex.: descartar um já descartado).
`422`	`INVALID_DISCARD_REASON`	Motivo de descarte que não vale para atendimento.
`422`	`CHECKLIST_PHASE_PENDING`	O atendimento tem pendência que impede a ação; a `message` diz qual.
`422`	`VISIT_SLOT_IN_PAST`	Horário de visita que já passou.
`409`	`VISIT_SLOT_TAKEN`	Horário indisponível para o corretor.
`409`	`VISIT_KEY_UNAVAILABLE`	Chave do imóvel indisponível no horário.
`409`	`VISIT_HANDOFF_PENDING`	Atendimento ainda sem corretor definido: a imobiliária agenda essa visita.
`422`	`VISIT_HAS_FEEDBACK`	Visita com parecer não reagenda.
`422`	`VISIT_REASON_REQUIRED`	Cancelar ou marcar não comparecimento pede motivo.
`422`	`VISIT_WITHOUT_PARECER`	Proposta precisa de visita com parecer.
`409`	`PROPOSAL_EXISTS`	Já existe proposta para o imóvel neste atendimento.
`409`	`ACTIVITY_FROM_VISIT`	Atividade criada por visita muda pela visita.
`409`	`CAPTACAO_REQUIRES_MODULE`	Lead de captação em convênio sem o módulo de Captação.

🏆 Regra de ouro

👍
Guie-se por estas três linhas

4xx → você corrige (dado, escopo, nome, limite).

5xx → nós corrigimos; pode reenviar depois de um tempo.

429 e reenvio de lead com o mesmo external_id são seguros de repetir.