Erros e boas práticas

Envelope de erro, códigos HTTP e tabela de code por situação.

Padrão de erro

{
  "success": false,
  "error": "Mensagem de erro",
  "code": "CODIGO_OPCIONAL"
}

Códigos HTTP

Código	Significado
`200` / `201` / `202`	Sucesso (sync / criado / enfileirado)
`400`	Validação / estado inválido
`401`	API key ausente ou inválida
`403`	Escopo insuficiente
`404`	Recurso não encontrado no workspace
`409`	Idempotência em andamento
`413`	Payload / arquivo grande demais
`429`	Rate limit ou quota mensal
`500`	Erro interno

code	HTTP	Situação
`IDEMPOTENCY_KEY_REQUIRED`	400	Faltou `Idempotency-Key` onde é obrigatório
`IDEMPOTENCY_IN_PROGRESS`	409	Mesma chave ainda `pending/scheduled/processing`
`workspace_quota_exceeded`	429	Cota mensal de envios esgotada
`INVALID_PHONE_E164`	400	Telefone fora de E.164 no upsert/contato
`UPSERT_KEY_REQUIRED`	400	Upsert sem phone/email
`STAGE_PIPELINE_MISMATCH`	400	Stage de outro pipeline no deal
`DELIVERY_ALREADY_SUCCEEDED`	400	Retry de delivery já com sucesso
`EXECUTION_NOT_CANCELLABLE`	400	Cancel de execução que não está `WAITING`
`NOT_FOUND`	404	Recurso / delivery / execução ausente no tenant
`UNAUTHORIZED`	401	API key inválida no controller
`INVALID_WEBHOOK_EVENTS`	400	Eventos de webhook inválidos