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

# Errores

> Códigos de error que puedes encontrar y cómo manejarlos.

Los errores siguen [RFC 7807](https://www.rfc-editor.org/rfc/rfc7807)
y se sirven con `Content-Type: application/problem+json`:

```http theme={null}
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json

{
  "type":     "https://errors.attestly.io/quota-exceeded",
  "title":    "Quota Exceeded",
  "status":   429,
  "detail":   "Monthly quota of 10000 requests exceeded for this billing period.",
  "instance": "/v1/evaluate",
  "quota": {
    "limit": 10000,
    "used":  10000,
    "period_started_at": "2026-04-15T00:00:00Z",
    "period_ends_at":   "2026-05-15T00:00:00Z"
  }
}
```

Haz match por la URI en `type` — es estable entre releases y
dereferenciable a documentación. `title` y `detail` son para humanos
y pueden reescribirse; no programes contra ellos.

Algunos tipos llevan **extension members** (el bloque `quota` arriba
es uno). Los miembros base (`type`, `title`, `status`, `detail`,
`instance`) siempre están; las extensions se documentan por tipo de
error más abajo.

## Autenticación & acceso

| Status | Type URI                                           | Cuándo                                                    |
| ------ | -------------------------------------------------- | --------------------------------------------------------- |
| 401    | `https://errors.attestly.io/authentication-failed` | API key ausente, malformada o revocada.                   |
| 402    | `https://errors.attestly.io/subscription-inactive` | Subscription no está activa.                              |
| 429    | `https://errors.attestly.io/quota-exceeded`        | Tope mensual alcanzado para el periodo de billing actual. |
| 429    | `https://errors.attestly.io/rate-limit-exceeded`   | Demasiadas requests en una ventana corta.                 |

Las respuestas 429 llevan headers `Retry-After` y `X-RateLimit-*`.
El tipo `quota-exceeded` lleva además una extension `quota` con
`limit`, `used`, `period_started_at`, `period_ends_at`. Ver
[Quotas](/es/reference/quotas).

## Validación

| Status | Type URI                                                | Cuándo                                                   |
| ------ | ------------------------------------------------------- | -------------------------------------------------------- |
| 422    | `https://errors.attestly.io/request-validation-failed`  | JSON malformado, tipos incorrectos, campos faltantes.    |
| 422    | `https://errors.attestly.io/program-validation-failed`  | Estructura del ruleset inválida (depth, refs, límites).  |
| 422    | `https://errors.attestly.io/program-compilation-failed` | Referencias del ruleset no se pudieron compilar.         |
| 422    | `https://errors.attestly.io/unknown-source`             | El ruleset referencia un source al que no tienes acceso. |

## Catálogo

| Status | Type URI                                            | Cuándo                            |
| ------ | --------------------------------------------------- | --------------------------------- |
| 404    | `https://errors.attestly.io/ruleset-not-found`      | `ruleset_id` no resuelve.         |
| 409    | `https://errors.attestly.io/ruleset-already-exists` | `(name, version)` ya está en uso. |

## Idempotencia

| Status | Type URI                                                | Cuándo                                               |
| ------ | ------------------------------------------------------- | ---------------------------------------------------- |
| 422    | `https://errors.attestly.io/idempotency-key-invalid`    | Header `Idempotency-Key` malformado.                 |
| 422    | `https://errors.attestly.io/idempotency-key-conflict`   | Misma clave, body distinto.                          |
| 429    | `https://errors.attestly.io/idempotency-key-exhausted`  | Demasiadas requests concurrentes con la misma clave. |
| 410    | `https://errors.attestly.io/idempotency-replay-expired` | La ventana de replay para esa clave ha expirado.     |

## Servidor (5xx)

| Status | Type URI                                          | Cuándo                                   |
| ------ | ------------------------------------------------- | ---------------------------------------- |
| 500    | `https://errors.attestly.io/internal-error`       | Error inesperado del servidor.           |
| 503    | `https://errors.attestly.io/database-unavailable` | Problema transitorio de infraestructura. |

Las respuestas 5xx son reintentables. Usa exponential backoff con
jitter; si persiste, contacta `support@attestly.io`.

## Fallas parciales (200)

Una falla de source o check no tira la request entera. La respuesta
es `200` pero `verdict.status = "degraded"` y el check afectado
lleva `status: "failed"` con un mensaje en `error`. Ver
[Verdicts](/es/concepts/verdicts).