Errors
Maneja errores de protocolo, autorización, dominio e idempotencia de forma segura.
Los errores HTTP usan un envelope estable:
{
"error": {
"code": "ERROR_CODE",
"message": "Human-readable explanation",
"details": {}
}
}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 o acción no permitida | 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. |
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.
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 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.