Saltar al contenido principal

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.

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

CuentaNo cuenta
POST /v1/evaluateGET /v1/sources
POST /v1/intersectionsGET /v1/rulesets (list/get)
POST /v1/distancePOST /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.

​
Idempotencia

Envía el header Idempotency-Key en toda solicitud facturable: 
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:
ResultadoHTTPSignificado
Misma clave, mismo body, cobrada200Replay — se devuelve el snapshot original.
Misma clave, body distinto422IDEMPOTENCY_KEY_CONFLICT — elige nueva clave.
Misma clave, demasiados reintentos429IDEMPOTENCY_KEY_EXHAUSTED — elige nueva clave.
Misma clave, snapshot expirado410IDEMPOTENCY_REPLAY_EXPIRED — clave reutilizable para nuevo cobro.
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).

​
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 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 para la lista completa de códigos.