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.
• Reserva previa. Los créditos se reservan/cobran al hacer dispatch del job — no al finalizarlo. Esto evita race conditions, pero también significa: un job abortado no devuelve los créditos automáticamente.

Mecánica de créditos

En términos de Laravel, antes de cada endpoint de pago vive el middleware credits:N. Comprueba el balance del team, cobra y solo entonces deja correr al controlador.

• Middleware credits:N → cobra N créditos antes del dispatch del job. Si el team baja de N, la API responde directamente con 402 Insufficient Credits sin dispatch.
• 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) ya están pagados al recibir la response. El worker en background hereda el cargo; un crash del worker no reembolsa automáticamente.

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/settings/api-documentation.

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.