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

# Facturación

> Cómo se cobran las solicitudes facturables, idempotencia y política de DEGRADED.

Esta página describe cómo la API mide y cobra las solicitudes. Aplica
cuando tu Organización tiene una suscripción activa y usa una clave
`atk_*`.

## Qué cuenta como solicitud facturable

| Cuenta                   | No cuenta                        |
| ------------------------ | -------------------------------- |
| `POST /v1/evaluate`      | `GET /v1/sources`                |
| `POST /v1/intersections` | `GET /v1/rulesets` (list/get)    |
| `POST /v1/distance`      | `POST /v1/rulesets` (create)     |
| `POST /v1/subjects`      | `?explain=true` (sólo metadatos) |

Lecturas de catálogo, escrituras de ruleset y llamadas
`?explain=true` nunca consumen cuota y nunca se cobran.

## Compuertas por solicitud

Toda solicitud facturable pasa por tres compuertas, en orden:

1. **Autenticación** — el bearer token debe ser una clave `atk_*`
   válida emitida a tu Organización.
2. **Suscripción** — tu suscripción debe estar activa. Una suscripción
   expirada o suspendida devuelve `402 SUBSCRIPTION_INACTIVE` y la
   solicitud no se ejecuta.
3. **Cuota** — debes estar dentro del tope mensual contratado para el
   período actual. Por encima del tope devuelve `429 QUOTA_EXCEEDED`
   y la solicitud no se ejecuta.

Una solicitud que falla en cualquiera de estas compuertas **no se
cobra**.

## Período de facturación

La cuota se cuenta contra tu **período de facturación de Stripe**, no
contra el mes calendario. Los límites vienen de tu suscripción —
típicamente el día del mes en que te suscribiste — y se devuelven en
los campos `period_started_at` / `period_ends_at` en respuestas
`429`. Ver [Cuotas y rate limits](/es/reference/quotas).

## Idempotencia

Envía el header `Idempotency-Key` en toda solicitud facturable:

```http theme={null}
POST /v1/evaluate
Idempotency-Key: client-job-2026-04-18-7842
Content-Type: application/json
Authorization: Bearer atk_live_...
```

Formato: `[A-Za-z0-9_:.-]{8,128}`. Cualquier otro valor devuelve
`422 IDEMPOTENCY_KEY_INVALID`.

Las claves tienen alcance por Organización. El contrato:

| Resultado                          | HTTP | Significado                                                         |
| ---------------------------------- | ---- | ------------------------------------------------------------------- |
| Misma clave, mismo body, cobrada   | 200  | Replay — se devuelve el snapshot original.                          |
| Misma clave, body distinto         | 422  | `IDEMPOTENCY_KEY_CONFLICT` — elige nueva clave.                     |
| Misma clave, demasiados reintentos | 429  | `IDEMPOTENCY_KEY_EXHAUSTED` — elige nueva clave.                    |
| Misma clave, snapshot expirado     | 410  | `IDEMPOTENCY_REPLAY_EXPIRED` — clave reutilizable para nuevo cobro. |

<Note>
  El replay devuelve la respuesta original **sin re-ejecutar la
  evaluación y sin cobrar de nuevo**. Es la forma segura de reintentar
  ante errores de red: la segunda solicitud o repite el resultado
  previo (sin cobro extra) o se ejecuta desde cero (un cobro en total).
</Note>

## Respuestas DEGRADED no se cobran

Una respuesta con `status: "degraded"` significa que al menos una
fuente no pudo ser evaluada por una razón de infraestructura (timeout
del proveedor upstream, error transitorio). La respuesta está
**incompleta**, no es incorrecta.

Por defecto, **las respuestas DEGRADED no consumen cuota y no se
cobran**. La `Idempotency-Key` queda reutilizable, así que puedes
reintentar la misma solicitud cuando la fuente upstream se recupere —
el reintento tendrá éxito (un cobro en total) o volverá a DEGRADED
(sigue en cero cobros).

Para los wrappers `/v1/intersections`, `/v1/distance` y
`/v1/subjects`, una fuente que falla individualmente se reporta con
`status: "failed"` en su `SourceOutcome`. La respuesta global puede
seguir siendo útil — las otras fuentes devolvieron datos — pero la
solicitud no se cobra.

Ver [Verdicts](/es/concepts/verdicts) para la semántica completa de
status/outcome.

## Estrategia de reintentos recomendada

1. Genera una `Idempotency-Key` nueva por job lógico (un UUID, o tu
   propio job id).
2. En `5xx`, error de red o `status: "degraded"`: reintenta con la
   **misma** clave. O repetirá un resultado ya cobrado, o ejecutará
   desde cero.
3. En `429 QUOTA_EXCEEDED`: detente hasta `period_ends_at` o
   contáctanos para subir el tope.
4. En `429 RATE_LIMIT_EXCEEDED`: espera `Retry-After` segundos con
   backoff exponencial y jitter.
5. En `422 IDEMPOTENCY_KEY_CONFLICT` o `429 IDEMPOTENCY_KEY_EXHAUSTED`:
   elige una clave nueva (la original está bloqueada a otro payload).

## Errores

Todos los errores relacionados con facturación siguen el envelope
estándar. Compara contra el campo `code`, no contra `title` ni
`detail`. Ver [Errores](/es/reference/errors) para la lista completa
de códigos.