Códigos de error ​

Estos son los códigos de error comunes a las bibliotecas de servicio con soporte oficial de DAT.

Cada código lleva dos valores — impacto y reintento — y algunos reciben además la etiqueta sospecha.

Impacto — el golpe que recibe el servicio ​

Es el criterio para lanzar una alerta. Solo se mira una cosa: "¿está el servicio detenido ahora mismo?".

Sin impacto no es un caso de alerta. Si todo el equipo de guardia tuviera que revisar porque llegó una entrada errónea una sola vez, la alerta perdería todo su sentido.

Sospecha — investigar si persiste ​

Los códigos con la etiqueta Sospecha forman parte de la operación normal cuando aparecen de forma aislada. Un cliente puede enviar valores erróneos en cualquier momento, y el papel de la biblioteca es precisamente filtrarlos.

Ahora bien, si estos errores se producen de forma persistente o concentrados desde un origen concreto, se trata de uno de estos dos casos.

• Anomalía de configuración — un despliegue incorrecto, clientes de una versión antigua que siguen activos, o certificados desalineados.
• Intento de intrusión — un intento de superar la verificación con tokens o claves manipulados, o un sondeo en busca de valores válidos.

Por eso, para estos códigos lo correcto es registrar el número de ocurrencias como métrica. Basta con avisar cuando se supere un umbral.

Reintento ​

Token ​

Problemas con la propia cadena del token recibido.

Certificado ​

El formato de la cadena del certificado y la cuestión de si ese certificado puede usarse ahora.

DAT_CERT_NOT_FOUND y DAT_CERT_NOT_SYNCED presentan los mismos síntomas, pero requieren reacciones distintas. El primero corresponde a un cid que nunca hemos emitido: esperar no cambia nada. El segundo se resuelve en cuanto se produce la sincronización.

Un DAT_CERT_NOT_FOUND aislado basta con filtrarlo; si la cifra crece de golpe, significa que el despliegue se ha desalineado o que circulan tokens falsificados.

Firma ​

Cifrado ​

Problemas de cifrado y descifrado de la carga útil secure.

Una carga útil secure vacía no es un error. Una entrada vacía produce una salida vacía y no se emite ningún código.

En la ruta que omite la verificación de firma, la etiqueta GCM es la única comprobación de integridad. Por eso DAT_CRYPTO_TAG_MISMATCH no se agrupa con los demás fallos de descifrado bajo un mismo código.

Clave ​

Tres casos que se parecen pero son distintos:

Gestor ​

El estado del objeto que guarda los certificados y se usa para emitir y verificar.

La causa (cause) de DAT_MANAGER_NO_ISSUABLE_CERTIFICATE es una de estas cuatro. Lo que hay que hacer difiere por completo según el origen.

Si el servidor emisor está configurado para recibir únicamente certificados de verificación, aparece DAT_CERT_VERIFY_ONLY. Esperar nunca lo resuelve, así que no es un caso de reintento.

Configuración ​

Problemas con los valores que pasa quien llama. La familia CONFIG está formada íntegramente por errores que hay que corregir en el código; si aparecen en producción, es que el despliegue es incorrecto.

Interno ​

Problemas del entorno de ejecución y del runtime.

DAT_INTERNAL_UNAVAILABLE se resuelve corrigiendo el entorno de despliegue; DAT_INTERNAL_UNKNOWN suele ser un fallo del runtime o un error de la biblioteca.

Sincronización CMS ​

Si no se usa la sincronización con el CMS, estos códigos no aparecen.

Los códigos en los que la sincronización se considera fallo permanente (UNAUTHORIZED, FORBIDDEN, ENDPOINT_NOT_FOUND, MALFORMED, IMPORT_FAILED) son todos críticos. Reintentar no resuelve nada mientras los certificados siguen expirando: si se deja sin atender, el servicio acabará necesariamente detenido.

En cambio, UNREACHABLE y SERVER_ERROR son parciales. Todo sigue funcionando con los certificados existentes y la sincronización se recupera sola en el siguiente ciclo — pero si los fallos continúan, al final se pasa a crítico. Coloca la alerta sobre el número de fallos consecutivos.

Servidor ​

Códigos que emite el servidor CMS. Los clientes no los generan, solo los reciben.

Sobre de respuesta:

{
  "code": "DAT_REQ_ALG_UNSUPPORTED",
  "details": { "algorithm": "BOGUS-ALG" }
}

Para los errores que surgen al crear y manipular certificados, el servidor usa tal cual los códigos comunes anteriores (DAT_CERT_*, DAT_KEY_*, DAT_CONFIG_*).

Al recibir un código del servidor ​

El cliente envuelve el código del servidor en su propio código CMS y conserva el original en cause.

Buscar por síntoma ​

Apéndice ​

Sintaxis de los códigos ​

DAT_<área>_<causa>

• Cuando la misma causa se produce en áreas distintas, el nombre de la causa es idéntico. DAT_TOKEN_MALFORMED y DAT_CERT_MALFORMED solo se diferencian en el objeto; el significado es el mismo.
• _UNKNOWN es exclusivamente el repliegue de cada área. No se usa con otro sentido, como "algoritmo desconocido" (para eso está _UNSUPPORTED).
• La cadena del código es un contrato público. El mensaje puede cambiarse libremente; el código, no.

Acceso según el cliente ​

Evento de seguridad solo devuelve true en los dos casos en los que la falsificación o la manipulación son seguras (DAT_SIG_MISMATCH, DAT_CRYPTO_TAG_MISMATCH). La etiqueta sospecha de este documento abarca más (llega hasta tokens, claves y peticiones manipulados); por ahora es solo una clasificación documental y no se expone en la API del cliente.

El nivel de impacto es igualmente una clasificación documental. Un mismo código puede golpear de forma distinta según dónde surja: DAT_KEY_INVALID, por ejemplo, no tiene impacto cuando sirve para filtrar un token entrante, pero hace fracasar toda la sincronización si aparece al leer un certificado durante la sincronización con el CMS.

Las causas subyacentes no se pierden. DAT_MANAGER_NO_ISSUABLE_CERTIFICATE y DAT_CMS_IMPORT_FAILED transmiten el origen mediante el encadenamiento de excepciones propio de cada lenguaje (cause / __cause__ / InnerException / Unwrap()).