Créditos y rate limits

Rankion cobra las acciones de pago de la API mediante un sistema simple de créditos. Los endpoints de solo lectura (listas GET, polls de status, vistas de detalle) son siempre gratis — solo se paga lo que consume tokens, APIs externas o tiempo de GPU.

¿Qué son los créditos?

• Una unidad común a toda la plataforma. Da igual si es generación de artículos, run de AI Visibility, pull de backlinks o edición de imágenes — todo se factura en créditos.
• Balance por team. Los créditos cuelgan del team, no del usuario. Todos los tokens del mismo team consumen del mismo bote.
• El momento del cobro depende del endpoint. Algunos endpoints cobran con la respuesta correcta, otros en el job o al terminar. Si un job falla, los créditos solo vuelven donde el endpoint prevé una devolución.

Mecánica de créditos

Delante de los endpoints de pago hay uno de dos middlewares, y solo uno de ellos cobra.

• credits:N → solo comprueba el balance. Si el team está por debajo de N, la API responde 402 Insufficient Credits y no arranca ningún job. El cobro llega después, en el controlador o el job.
• credits-auto:N → misma comprobación, y cobra N créditos cuando la respuesta es 2xx. 4xx y 5xx no cuestan nada.
• Refrescos inline (p. ej. Keyword Explorer con ?cache=false) tiran un cobro fijo de 50 créditos — el cache-bust es la operación cara.
• Jobs asíncronos (HTTP 202): con credits-auto:N el cobro ya está hecho al recibir la respuesta. Con credits:N cobra el propio job. Un crash del worker solo reembolsa donde el endpoint lo prevé; POST /v1/google/gsc/properties/{p}/sync no reembolsa.

Coste en créditos (selección)

Lista completa: docs/API_REFERENCE.md — los 137 endpoints con su columna de créditos. Tabla en vivo: rankion.ai/api-docs.

Insufficient Credits — HTTP 402

Si el balance del team no alcanza para la acción, la API responde con 402 Payment Required:

{
  "message": "Insufficient credits",
  "error": "insufficient_credits",
  "required": 10,
  "available": 4
}

El job no se dispatcha; quien llama puede informar al usuario o recargar créditos. El balance actual lo obtienes en cualquier momento mediante la Credit API.

Credit API

# Balance actual + info del plan
curl -H "Authorization: Bearer $TOKEN" "$BASE/credits"

# Historial de movimientos (paginado)
curl -H "Authorization: Bearer $TOKEN" "$BASE/credits/history"

Ejemplo de response para GET /v1/credits:

{
  "data": {
    "balance": 1240,
    "plan": "growth",
    "monthly_allotment": 5000,
    "renews_at": "2026-05-15T00:00:00Z"
  }
}

GET /v1/credits/history devuelve por entrada: created_at, delta (negativo = consumo, positivo = top-up), endpoint, reference_id (p. ej. el ID del artículo) y balance_after. Así puedes asignar exactamente qué acción consumió qué créditos.

Rate limits

Además del sistema de créditos hay un rate limit clásico de requests por token:

• ~60 requests por minuto por token como estándar para rutas auth:sanctum.
• Si el cliente supera el límite, la API responde con 429 Too Many Requests más el header Retry-After.
• Por eso, los polling loops sobre jobs asíncronos no deben ser más agresivos que cada 5 segundos — y siempre con backoff exponencial ante 429.

Algunos endpoints tienen límites más estrictos, p. ej.:

• POST /v1/tracking-projects/{id}/generate-report → 1 request / 30 min / proyecto. Si no, 429 {error: "rate_limited"}.
• Public Share Unlock (POST /share/{token}/unlock) → 5 / minuto (protección anti brute-force).

Consejos para gastar menos

• Aprovecha la caché. El Explorer y endpoints similares cachean 60 min — usa ?cache=false solo si realmente necesitas datos frescos.
• Polling antes de un nuevo dispatch. Antes de un segundo POST /generate, verifica con un GET si el primer job ya está corriendo (status == processing). De lo contrario pagas dos veces.
• Usa include= donde esté soportado — ahorra roundtrips y costes de cuota frente a terceros.

Continúa con API de Proyectos · vuelve a Autenticación.