Saltar al contenido principal
Códigos de error canónicos y veredictos utilizados en toda la plataforma Truthlocks. Estos códigos son estables y pueden utilizarse para el manejo programático de errores.

Veredictos de verificación

Razones de verificación

Cuando llama al punto final de verificación, la respuesta incluye una matriz reasons con contexto adicional. Estos códigos de motivo son informativos y aparecen junto al veredicto:

Códigos de error de la API

General

Atestaciones y emisores

Claves de API

Consumidor

Identidad y DID

SSO

Política y gobernanza

Facturación y límites

Residencia de datos

Errores reintentables vs. terminales

Al decidir si reintentar una solicitud fallida, use el código de estado HTTP para determinar si el error es transitorio o permanente.

Reintentable (transitorio)

Estos errores son reintentados automáticamente por los SDKs cuando MaxRetries (o equivalente) está configurado:

Terminal (no reintentar)

Estos errores indican un problema con la solicitud que no se resolverá reintentando:
Los tres SDK manejan los errores reintentables automáticamente con retroceso exponencial y fluctuación. Solo necesita lógica de reintento manual si ha deshabilitado los reintentos automáticos o desea un comportamiento personalizado además de los valores predeterminados del SDK.

Formato de respuesta de error

Cada respuesta de error devuelve un objeto JSON con dos campos:
  • code — un código de error estable y legible por máquina de las tablas anteriores. Úselo para el manejo programático de errores.
  • message — una descripción legible por humanos de lo que salió mal. Los mensajes pueden cambiar entre versiones; no los compare programáticamente.
Los mensajes de error que expondrían detalles de la infraestructura (como cadenas de conexión de bases de datos o nombres de host internos) se reemplazan automáticamente con un mensaje genérico antes de ser devueltos al cliente. Los detalles originales se registran solo en el lado del servidor.

Errores de puerta de enlace (RFC 7807)

Cuando una solicitud llega a la puerta de enlace de la API pero no coincide con ninguna ruta válida, la puerta de enlace devuelve una respuesta de error estructurada siguiendo la especificación RFC 7807 Problem Details. Esto se aplica a los errores 404 Not Found y 405 Method Not Allowed a nivel de la puerta de enlace.

Formato de respuesta

Los errores de puerta de enlace usan application/problem+json como tipo de contenido e incluyen cuatro campos:

Cuando vea estos errores

  • 404 Not Found — La ruta de la solicitud no coincide con ninguna ruta de API. Verifique la URL, incluido el prefijo de versión /v1/ y el nombre del recurso.
  • 405 Method Not Allowed — La ruta de la solicitud existe, pero el método HTTP que utilizó (por ejemplo, DELETE en un punto final de solo lectura) no es compatible. Consulte la referencia de la API para el método correcto.

Manejo de errores de puerta de enlace en el código

Si analiza las respuestas de error mediante programación, compruebe el encabezado Content-Type para distinguir los errores de puerta de enlace de los errores de aplicación:
  • application/problem+json — Error a nivel de puerta de enlace (RFC 7807). Use los campos status y title.
  • application/json — Error a nivel de aplicación. Use los campos code y message.
Los SDK de Truthlocks manejan ambos formatos de error automáticamente. Solo necesita distinguirlos si está llamando a la API directamente.

Enumeraciones canónicas

Algoritmo

* Ed25519 * ES256 * ES384 * ES512 * RS256 * RS384 * RS512 * PS256 * PS384 * PS512

Estado del emisor

  • pending * trusted * suspended * revoked

Nivel de confianza

  • self_issued * verified_org * regulated_issuer

Estado de la clave

  • ACTIVE * DISABLED * EXPIRED * COMPROMISED

Estado de la atestación

* ACTIVE * REVOKED * SUPERSEDED

Clasificación de riesgo

  • unknown * low * medium * high * critical