Errores y códigos

Todo error de la API v1 vuelve en el mismo envelope:

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

message es legible (y puede cambiar); code es estable — programa contra el código, no contra el mensaje. Trata cualquier código desconocido según el status HTTP.

Códigos por status HTTP

400 — solicitud inválida

Código	Cuándo
VALIDATION_ERROR	Body o query inválidos; details trae los campos
INVALID_ID	ID fuera del formato UUID
INVALID_WEBHOOK_URL	URL de webhook rechazada (no HTTPS o red interna)
INVALID_WEBHOOK_AUTH	Configuración de autenticación del webhook incompleta
SSRF_BLOCKED	La URL resuelve hacia un destino bloqueado
INVALID_RECIPIENT	Destinatario inválido para el canal de la notificación
INVALID_STATUS_FOR_RESEND	Notificación en un estado que no permite reenvío
MISSING_CONTENT_PLACEHOLDER	Layout de e-mail sin {{content}}
SELF_DEACTIVATION / SELF_ROLE_CHANGE	Intento de desactivar la propia cuenta / cambiar el propio rol
EMAIL_EXISTS	E-mail ya registrado

401 — no autenticado

Código	Cuándo
UNAUTHORIZED	Clave ausente, inválida, revocada o expirada; sesión inválida

403 — sin permiso

Código	Cuándo
FORBIDDEN	El actor no tiene el permiso requerido
API_KEY_FORBIDDEN	Clave de API intentando un recurso administrativo o fuera del scope; required indica el permiso que faltó

404 — no encontrado

Código	Cuándo
NOT_FOUND	Recurso inexistente (o de otra organización)
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 cuando la ruta valida un vínculo

409 — conflicto de estado

Código	Cuándo
CONFLICT / DUPLICATE	El registro entra en conflicto con uno existente (documento, nombre...) o con el estado actual — ej.: aceptar un acuerdo que ya no está proposed (ya aceptado o aceptación concurrente)
USER_EXISTS / INVITATION_EXISTS	Invitación a un e-mail ya usuario / ya invitado
LAST_ADMIN	Degradar o desactivar al último administrador
ROLE_IN_USE, RULE_IN_USE, STEP_IN_USE, WORKSPACE_IN_USE, COMPANY_IN_USE, HAS_BRANCHES	Eliminación bloqueada: el recurso está en uso
CHARGE_HAS_RELATED_RECORDS	Un cobro con notificaciones/interacciones/negativaciones/protestos no puede eliminarse; details trae los conteos
ENDPOINT_INACTIVE	Reenvío de webhook a un endpoint inactivo
IDEMPOTENCY_KEY_REUSED	Misma X-Idempotency-Key con body distinto
IDEMPOTENCY_REQUEST_IN_PROGRESS	Solicitud concurrente con la misma clave aún en curso
NOT_READY	El recurso todavía no está listo (ej.: exportación en procesamiento)

410, 413, 422

Status	Código	Cuándo
410	EXPIRED	Recurso expirado (ej.: descarga de exportación vencida)
413	FILE_TOO_LARGE	Archivo de importación por encima del límite
422	DEFAULT_IMMUTABLE	El workspace principal / la empresa matriz no pueden eliminarse
422	SYSTEM_ROLE_IMMUTABLE	Los roles de sistema no pueden editarse/eliminarse

429 y 500

Status	Código	Cuándo
429	RATE_LIMITED	Límite de solicitudes de la clave excedido; reintenta con backoff (detalles)
500	INTERNAL_ERROR	Fallo inesperado en el servidor; reintenta con la misma X-Idempotency-Key

Receta de manejo

• 4xx excepto 409/429: error tuyo; corrige la solicitud antes de repetir.
• 409: lee el código; casi siempre es una regla de negocio protegiendo el estado (no se resuelve con reintentos).
• 429 y 5xx: reintenta con backoff exponencial y la misma clave de idempotencia — la idempotencia garantiza que nada se ejecuta dos veces.