Errores
Maneja errores de protocolo, autorización, dominio e idempotencia de forma segura.
Los errores HTTP usan un envelope estable:
{
"error": {
"code": "ERROR_CODE",
"message": "causa_exacta",
"details": {}
}
}code es la familia del error; message identifica la causa exacta y es el valor que conviene ramificar en tu código. details aporta contexto cuando existe (por ejemplo, los scopes que faltan).
Códigos HTTP
| Estado | Significado | Acción recomendada |
|---|---|---|
400 | Request o JSON inválido | Corregir el request; no reintentar sin cambios. |
401 | API key ausente o inválida | Corregir autenticación server-side. |
403 | Scope insuficiente, origen no permitido o producto no habilitado | Revisar permisos; nunca degradar a ALLOW. |
404 | Recurso del tenant no encontrado | Verificar el identificador y el tenant. |
409 | Conflicto de idempotencia o estado | No cambiar la clave para ocultar un conflicto semántico. |
422 | Precondición de dominio incumplida | Corregir estado o datos antes de reintentar. |
500 | INTERNAL_ERROR o inconsistencia interna clasificada | No asumir consentimiento ni autorización; reintentar con backoff sólo si es seguro. |
503 | Una dependencia necesaria no está disponible | Reintentar con backoff; no degradar el flujo. |
Un DENY de negocio se entrega como HTTP 200 y es una decisión válida. Un error 5xx significa que Consensa no pudo producir o confirmar una decisión confiable; nunca lo conviertas en ALLOW.
RATE_LIMITED y AUTHORIZATION_STATE_UNAVAILABLE existen en el vocabulario de dominio, pero no se anuncian como responses de una operación Integration API v1 mientras el transporte actual no las emita.
Errores que vas a ver seguido
error.message | Dónde | Qué revisar |
|---|---|---|
idempotency_key_required | Toda escritura con Idempotency-Key | Falta el header. |
consent_api_scope_required | Cualquier operación | error.details.missingScopes dice cuál falta. |
unsupported_identifier | Resolve y creación de sesiones | Sólo existen {cl,rut} y {email,email}. |
customer_resolution_conflict | Resolve | El identifier ya está asociado a otro userReference. |
verified_not_caller_controlled | Resolve y creación de sesiones | verified no lo controla quien llama. |
ORIGIN_NOT_ALLOWED | Creación de sesiones, canje del ticket | El origin no está en la lista del tenant, o tu página no corre en él. |
CONFIG_NOT_PUBLISHED | Metadata y creación de sesiones | El Flow no tiene versión publicada utilizable. |
REDEC_NOT_ENABLED | Operaciones REDEC | El producto REDEC no está habilitado para tu tenant. |
internal_consent_code_is_server_generated | Otorgamiento REDEC | Lo genera Consensa; no lo envíes. |
Reintentos
Reintenta timeouts, errores transitorios y respuestas 5xx con backoff y límite. En escrituras, conserva la misma Idempotency-Key y el mismo payload para el mismo comando semántico.
Una respuesta fallida, ausente o ambigua nunca equivale a consentimiento ni autorización. Para authorization/check y redec/accesses/authorize, continúa sólo ante un ALLOW o un authorized explícito.
Eventos del Web Component
El evento consensa:error contiene sólo interactionReference y un code sanitizado. Úsalo para feedback de interfaz; la investigación y reconciliación deben basarse en respuestas server-side y observabilidad autorizada.