> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Referencia de códigos de error

> 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.

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

| Veredicto | Salida CLI | Descripción |
| - | - | - |
| VALID | 0 | Atestación verificada con éxito |
| ALTERED | 10 | El hash de la carga útil no coincide |
| REVOKED | 11 | La atestación ha sido revocada |
| KEY\_COMPROMISED | 12 | Clave de firma marcada como comprometida |
| KEY\_EXPIRED | 13 | La clave de firma ha caducado |
| LOG\_PROOF\_FAILED | 14 | Falló la verificación de la prueba del registro de transparencia |
| SIGNATURE\_INVALID | 15 | Falló la verificación de la firma criptográfica |

### Razones de verificación

Cuando llama al [punto final de verificación](https://docs.truthlocks.com/es/api-reference/verify.md), la respuesta incluye una matriz `reasons` con contexto adicional. Estos códigos de motivo son informativos y aparecen junto al veredicto:

| Razón | Veredicto | Descripción |
| :- | :- | :- |
| `document_hash_mismatch` | `ALTERED` | El `document_hash_hex` que proporcionó no coincide con el hash almacenado en el momento de la acuñación |
| `document_hash_not_stored` | (cualquiera) | La atestación se acuñó sin un hash de documento, por lo que se omitió la verificación del hash de documento |

## Códigos de error de la API

### General

| Código | HTTP | Descripción |
| :- | :- | :- |
| `INVALID_INPUT` | 400 | Falló la validación de la solicitud |
| `INVALID_REQUEST` | 400 | El cuerpo de la solicitud o los parámetros están mal formados |
| `INVALID_ID` | 400 | El identificador no es un UUID válido |
| `NOT_FOUND` | 404 | Recurso no encontrado |
| `UNAUTHORIZED` | 401 | Autenticación requerida |
| `FORBIDDEN` | 403 | Permiso denegado |
| `CONFLICT` | 409 | Conflicto de estado del recurso |
| `INTERNAL_ERROR` | 500 | Ocurrió un error inesperado del servidor |
| `DB_ERROR` | 500 | Falló una operación de base de datos |

### Atestaciones y emisores

| Código | HTTP | Descripción |
| :- | :- | :- |
| `ISSUER_NOT_TRUSTED` | 403 | El emisor debe estar en estado `trusted` para acuñar atestaciones |
| `KEY_INACTIVE` | 400 | La clave de firma no está activa |

### Claves de API

| Código | HTTP | Descripción |
| :- | :- | :- |
| `NAME_REQUIRED` | 400 | Se requiere un nombre de clave |
| `KEY_ID_REQUIRED` | 400 | Falta el parámetro ID de clave |
| `KEY_NOT_FOUND` | 404 | Clave API no encontrada |
| `KEY_LIMIT` | 409 | Se alcanzó el número máximo de claves API activas (5 por consumidor) |

### Consumidor

| Código | HTTP | Descripción |
| :- | :- | :- |
| `CONSUMER_REQUIRED` | 400 | Se requiere una referencia de correo electrónico del consumidor |

### Identidad y DID

| Código | HTTP | Descripción |
| :- | :- | :- |
| `MISSING_DID` | 400 | Se requiere el parámetro DID |
| `DID_NOT_FOUND` | 404 | DID no encontrado o el emisor asociado ha sido revocado |
| `MISSING_ID` | 400 | Se requiere el parámetro ID de emisor |
| `EMAIL_NOT_VERIFIED` | 403 | La dirección de correo electrónico no ha sido verificada |

### SSO

| Código | HTTP | Descripción |
| :- | :- | :- |
| `DISCOVERY_FAILED` | 400 | No se pudo cargar la configuración de descubrimiento de OIDC |
| `METADATA_FETCH_FAILED` | 400 | No se pudieron obtener los metadatos del IdP SAML |
| `CRYPTO_ERROR` | 500 | Falló una operación de cifrado |
| `TEST_FAILED` | 400 | La prueba de conexión SSO no tuvo éxito |
| `AUTH_FAILED` | 401 | Falló la autenticación SSO |
| `INVALID_STATE` | 401 | El parámetro de estado de OAuth o SAML no es válido |
| `EXPIRED_SESSION` | 401 | La sesión de inicio de sesión SSO ha expirado |
| `REPLAY_DETECTED` | 401 | El token de estado de OAuth o SAML ya ha sido utilizado |
| `CONFIG_ERROR` | 500 | La configuración de SSO falta o no es válida |

### Política y gobernanza

| Código | HTTP | Descripción |
| :- | :- | :- |
| `POLICY_VIOLATION` | 403 | La solicitud viola una política activa |

### Facturación y límites

| Código | HTTP | Descripción |
| :- | :- | :- |
| `BILLING_LIMIT` | 402 | Cuota de facturación agotada para el ciclo actual |
| `LIMIT_REACHED` | 429 | Límite de protección mensual alcanzado |
| `SEAT_LIMIT` | 402 | Se alcanzó el límite de puestos del equipo: actualice su plan o elimine un miembro existente |

### Residencia de datos

| Código | HTTP | Descripción |
| :- | :- | :- |
| `REGION_MISMATCH` | 409 | El inquilino está anclado a una región diferente a la que procesa la solicitud |

## 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](https://docs.truthlocks.com/es/sdk/go.md) cuando `MaxRetries` (o equivalente) está configurado:

| Estado HTTP | Código | Cuándo reintentar |
| :- | :- | :- |
| `408` | Tiempo de espera de la solicitud | Inmediatamente — el servidor no recibió la solicitud a tiempo |
| `429` | `RATE_LIMITED` | Después de la duración especificada en el encabezado `Retry-After` |
| `500` | `INTERNAL_ERROR` | Con retroceso exponencial — problema transitorio del servidor |
| `502` | Bad Gateway | Con retroceso exponencial — servicio ascendente no disponible |
| `503` | Servicio no disponible | Con retroceso exponencial — servicio temporalmente sobrecargado |
| `504` | Gateway Timeout | Con retroceso exponencial — el servicio ascendente agotó el tiempo de espera |

### Terminal (no reintentar)

Estos errores indican un problema con la solicitud que no se resolverá reintentando:

| Estado HTTP | Códigos de ejemplo | Acción |
| :- | :- | :- |
| `400` | `INVALID_INPUT`, `INVALID_REQUEST` | Corregir la carga útil de la solicitud |
| `401` | `UNAUTHORIZED` | Verifique su clave API o token de autenticación |
| `403` | `FORBIDDEN`, `ISSUER_NOT_TRUSTED`, `POLICY_VIOLATION` | Comprobar permisos o estado del emisor |
| `404` | `NOT_FOUND` | Verifique que el ID de recurso exista |
| `409` | `CONFLICT` | Resuelva el conflicto de estado antes de reintentar |

> [!TIP]
>
> 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:

```json theme={null}
{
  "code": "ISSUER_NOT_TRUSTED",
  "message": "Issuer must be in trusted status to mint attestations"
}
```

* **`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.

> [!NOTE]
>
> 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](https://www.rfc-editor.org/rfc/rfc7807). 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:

```json theme={null}
{
  "type": "https://docs.truthlocks.com/ops/errors",
  "title": "Not Found",
  "status": 404,
  "detail": "The requested path does not match any API route."
}
```

| Campo | Descripción |
| :- | :- |
| `type` | Una referencia URI que identifica el tipo de error. Apunta a esta página de documentación. |
| `title` | Un breve resumen del error. O `Not Found` o `Method Not Allowed`. |
| `status` | El código de estado HTTP — `404` o `405`. |
| `detail` | Una explicación legible por humanos del error específico. |

### 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](https://docs.truthlocks.com/es/api-reference/attestations/mint.md) 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`.

```javascript theme={null}
const res = await fetch("https://api.truthlocks.com/v1/nonexistent");
const contentType = res.headers.get("content-type");

if (contentType?.includes("application/problem+json")) {
  // Gateway error — RFC 7807 format
  const problem = await res.json();
  console.error(`${problem.status} ${problem.title}: ${problem.detail}`);
} else {
  // Application error — standard format
  const error = await res.json();
  console.error(`${error.code}: ${error.message}`);
}
```

> [!TIP]
>
> Los [SDK de Truthlocks](https://docs.truthlocks.com/es/sdk/js.md) manejan ambos formatos de error automáticamente. Solo necesita distinguirlos si está llamando a la API directamente.

## Enumeraciones canónicas

> [card] Algoritmo
>
> \* `Ed25519` \* `ES256` \* `ES384` \* `ES512` \* `RS256` \* `RS384` \* `RS512` \* `PS256` \* `PS384` \* `PS512`

> [card] Estado del emisor
>
> * `pending` \* `trusted` \* `suspended` \* `revoked`

> [card] Nivel de confianza
>
> * `self_issued` \* `verified_org` \* `regulated_issuer`

> [card] Estado de la clave
>
> * `ACTIVE` \* `DISABLED` \* `EXPIRED` \* `COMPROMISED`

> [card] Estado de la atestación
>
> \* `ACTIVE` \* `REVOKED` \* `SUPERSEDED`

> [card] Clasificación de riesgo
>
> * `unknown` \* `low` \* `medium` \* `high` \* `critical`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.