Erros e códigos

Todo erro da API v1 volta no mesmo envelope:

{
  "message": "Valor original deve ser positivo",
  "code": "VALIDATION_ERROR",
  "details": { "...": "opcional; ex.: erros de validacao campo a campo" }
}

message é legível (e pode mudar); code é estável — programe contra o código, não contra a mensagem. Trate qualquer código desconhecido pelo status HTTP.

Códigos por status HTTP

400 — requisição inválida

Código	Quando
VALIDATION_ERROR	Body ou query inválidos; details traz os campos
INVALID_ID	ID fora do formato UUID
INVALID_WEBHOOK_URL	URL de webhook recusada (não-HTTPS ou rede interna)
INVALID_WEBHOOK_AUTH	Configuração de autenticação do webhook incompleta
SSRF_BLOCKED	URL resolve para destino bloqueado
INVALID_RECIPIENT	Destinatário inválido para o canal da notificação
INVALID_STATUS_FOR_RESEND	Notificação em status que não permite reenvio
MISSING_CONTENT_PLACEHOLDER	Layout de e-mail sem {{content}}
SELF_DEACTIVATION / SELF_ROLE_CHANGE	Tentativa de desativar a própria conta / mudar o próprio role
EMAIL_EXISTS	E-mail já cadastrado

401 — não autenticado

Código	Quando
UNAUTHORIZED	Chave ausente, inválida, revogada ou expirada; sessão inválida

403 — sem permissão

Código	Quando
FORBIDDEN	O ator não tem a permissão exigida
API_KEY_FORBIDDEN	Chave de API tentando recurso administrativo ou fora do escopo; required indica a permissão que faltou

404 — não encontrado

Código	Quando
NOT_FOUND	Recurso inexistente (ou de outra organização)
PERSON_NOT_FOUND, CHARGE_NOT_FOUND, CLASSIFICATION_NOT_FOUND, COLLECTION_RULE_NOT_FOUND, STEP_NOT_FOUND, MESSAGE_TEMPLATE_NOT_FOUND, NOTIFICATION_NOT_FOUND	Variantes específicas quando a rota valida um vínculo

409 — conflito de estado

Código	Quando
CONFLICT / DUPLICATE	Registro conflita com um existente (documento, nome...) ou com o estado atual — ex.: aceitar um acordo que não está mais proposed (já aceito ou aceite concorrente)
USER_EXISTS / INVITATION_EXISTS	Convite para e-mail já usuário / já convidado
LAST_ADMIN	Rebaixar ou desativar o último administrador
ROLE_IN_USE, RULE_IN_USE, STEP_IN_USE, WORKSPACE_IN_USE, COMPANY_IN_USE, HAS_BRANCHES	Exclusão bloqueada: o recurso está em uso
CHARGE_HAS_RELATED_RECORDS	Cobrança com notificações/interações/negativações/protestos não pode ser excluída; details traz as contagens
ENDPOINT_INACTIVE	Re-envio de webhook para endpoint inativo
IDEMPOTENCY_KEY_REUSED	Mesma X-Idempotency-Key com body diferente
IDEMPOTENCY_REQUEST_IN_PROGRESS	Requisição concorrente com a mesma chave ainda em curso
NOT_READY	Recurso ainda não está pronto (ex.: exportação em processamento)

410, 413, 422

Status	Código	Quando
410	EXPIRED	Recurso expirado (ex.: download de exportação vencido)
413	FILE_TOO_LARGE	Arquivo de importação acima do limite
422	DEFAULT_IMMUTABLE	Workspace principal / empresa matriz não podem ser removidos
422	SYSTEM_ROLE_IMMUTABLE	Roles de sistema não podem ser editados/excluídos

429 e 500

Status	Código	Quando
429	RATE_LIMITED	Limite de requisições da chave excedido; re-tente com backoff (detalhes)
500	INTERNAL_ERROR	Falha inesperada no servidor; re-tente com a mesma X-Idempotency-Key

Receita de tratamento

• 4xx exceto 409/429: erro seu; corrija a requisição antes de repetir.
• 409: leia o código; quase sempre é uma regra de negócio protegendo o estado (não é retry que resolve).
• 429 e 5xx: re-tente com backoff exponencial e a mesma chave de idempotência — a idempotência garante que nada é executado duas vezes.