Créditos y límites

AstroWay utiliza un modelo de créditos en lugar de un simple contador de solicitudes.

Esto es más justo: los endpoints ligeros (/planets) cuestan 10 créditos, los pesados (/rectification) - 500.

Dos tipos de límites

1. Presupuesto diario/mensual de créditos

La cantidad de créditos al mes depende del plan:

Plan	Créditos/mes	Límite diario
Free	10 000	~333
Indie	50 000	~1 667
Starter	200 000	~6 667
Pro	800 000	~26 667
Business	3 500 000	~116 666
Enterprise	Custom	Custom

Una vez agotados los créditos, las siguientes solicitudes devuelven 402 Payment Required (Free) o activan la facturación por exceso (overage) (Indie+).

2. Límite de tasa (solicitudes por minuto)

Plan	RPM
Free	10 req/min
Indie	30 req/min
Starter	120 req/min
Pro	400 req/min
Business	1 000 req/min
Enterprise	Custom

El límite de tasa es una ventana deslizante. Si realizaste 120 solicitudes en 10 segundos, los siguientes 50 segundos con esta clave devolverán 429.

Si una clave tiene una lista de orígenes permitidos, cada entrada de la lista recibe su parte de este límite: el límite de la clave se divide por el número de entradas, redondeado hacia arriba. Un solo sitio con un widget incrustado no puede consumir la cuota por la que paga el propietario de la clave, mientras que sus otros dominios permanecen operativos. El límite total de la clave no aumenta: las partes lo dividen, no se suman a él.

El contador se lleva por la entrada, no por el host que llegó. La entrada *.example.com es un solo contador para todos los subdominios, de lo contrario, la restricción se eludiría inventando un nuevo subdominio para cada solicitud. Cuando hay una sola entrada en la lista, la parte es igual al límite y nada cambia.

3. Endpoints públicos (sin clave)

Los 14 diccionarios de referencia /v1/reference/* (signs, planets, houses, aspects, elements, modalities, polarities, dignities, decans, nakshatras, lots, asteroids, zodiac-systems, glyphs) se sirven públicamente, sin X-Api-Key y cuestan 0 créditos. La restricción es de 30 solicitudes / hora desde una misma IP. Estos mismos datos se exponen como Recursos MCP astroway://reference/<slug> para agentes LLM.

El mismo límite se aplica al resto de los namespaces públicos: /v1/public/*, /v1/embed/*, /v1/i18n/*.

Cuota para renderizado en el servidor

Las 30 solicitudes por hora están diseñadas para el navegador: cada visitante aporta su propia IP y su propia cuota. Pero si las solicitudes las hace tu servidor (plugin de WordPress, SSR, precalentamiento de caché), una única dirección actúa en nombre de todos los visitantes y agota el límite en unas pocas recargas de página.

Para este caso, envía el encabezado X-AstroWay-Site-URL con la dirección del sitio:

X-AstroWay-Site-URL: https://example.com/

Modo	Límite
Sin encabezado	30 solicitudes / hora por IP; los widgets `/v1/embed/*` tienen un límite separado de 120 / hora por IP
Con encabezado	300 solicitudes / hora por sitio, techo de 600 / hora por IP

El encabezado está permitido en CORS y no es una credencial, por lo que el techo por IP permanece: no importa cuántos dominios se nombren desde una misma dirección, en total, no se enviarán más de 600 solicitudes por hora desde allí. Ambos contadores son necesarios simultáneamente: el contador del sitio se activa cuando un sitio accede desde muchas direcciones (CDN, balanceador), el contador de IP se activa cuando muchas solicitudes provienen de una misma dirección.

Una llamada no siempre es una unidad. Un endpoint público pesado consume más de la misma cesta, y no obtiene una separada. POST /v1/public/synastry cuesta 3, porque son dos cartas y una matriz de aspectos de 45 celdas: el techo práctico para este es de 10 por hora desde una dirección no declarada, 100 para un sitio declarado y 200 por dirección. Todo lo demás cuesta 1. Cuando una llamada cuesta más de una unidad, la respuesta lo indica en el encabezado X-RateLimit-Cost, y una llamada que cuesta más de lo que queda en la cesta es rechazada, no va a números negativos.

Qué contador es el más restrictivo ahora lo indica el encabezado de la respuesta X-RateLimit-Scope (ip o site). El resto de los encabezados X-RateLimit-* describen solo este, es decir, solo uno de los dos contadores. El segundo se ve en X-RateLimit-Counters:

X-RateLimit-Scope: site
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 297
X-RateLimit-Counters: ip=597/600, site=297/300

El formato es scope=restante/límite separado por comas. El encabezado solo aparece cuando realmente hay dos contadores: una llamada anónima con X-AstroWay-Site-URL. Una llamada con una clave de pago se cuenta según tu clave y tu tarifa, allí hay un solo contador y no hay encabezado. Léelo si renderizas desde el servidor varios dominios desde una misma dirección: la cesta del sitio es propia de cada dominio, pero el techo por IP es compartido, y es este el que se alcanza primero.

Almacena en caché las respuestas en tu lado: el horóscopo diario no cambia durante el día, y una caché hasta medianoche elimina completamente la cuestión del límite.

Clave de pago en endpoints públicos. /v1/public/* y /v1/embed/* funcionan sin clave, pero si la pasas (X-Api-Key), la solicitud se cuenta según tu tarifa, no según la cuota anónima, y la respuesta no tiene marca de agua gratuita. Esto tiene sentido para el renderizado del lado del servidor: una máquina accede en nombre de todos los visitantes, y 300/hora anónimos son insuficientes para ella.

Tabla de costos

Una tabla completa y transparente con todos los 771+ endpoints y sus costos está en la página Costo de los endpoints. DivineAPI/AstrologyAPI/Prokerala no publican tal tabla. Orientación rápida:

Nivel	Créditos	Tiempo típico	Ejemplos
1	10	< 50 ms	`/planets`, `/moon-voc`, `/iching`
2	20	50–200 ms	`/chart`, `/harmonics`, `/horary`
3	50	200–500 ms	`/synastry`, `/progressions`, `/acg`
4	100	> 500 ms	`/transit-calendar`, `/forecast-calendar`
5	250	varios s	`/rectification/trutine`
6	500	hasta 120 s	`/rectification`

Encabezados de respuesta

Cada respuesta contiene:

X-Credits-Used: 20
X-Credits-Remaining: 9980
X-Credits-Limit: 10000
X-Credits-Reset: 2026-05-01T00:00:00Z
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1714521600
X-RateLimit-Origin-Limit: 60
X-RateLimit-Origin-Remaining: 59
X-Request-Id: 8aec43e9bc749b37e998a489bbad1757

X-Credits-Used: cuánto se ha deducido por esta solicitud
X-Credits-Remaining: saldo restante del presupuesto mensual
X-Credits-Limit: presupuesto total de créditos al mes (según el plan)
X-Credits-Reset: fecha ISO-8601 de la actualización del saldo
X-RateLimit-*: estado actual de la ventana deslizante (formato estándar)
- X-RateLimit-Scope: qué contador es el más restrictivo ahora: ip, site o key. El valor key significa que la solicitud se ha contado según tu clave y el límite de tu tarifa, no según la cuota anónima.
- X-RateLimit-Counters: en un endpoint público, llamado con X-AstroWay-Site-URL, todos los contadores por los que se contó la solicitud, en formato scope=restante/límite. Los encabezados anteriores describen solo el más restrictivo.
- X-RateLimit-Reset: el momento en que la solicitud más antigua saldrá de la ventana, es decir, cuando se libere un slot. Este no es el momento de la apertura completa del bucket: después de él pasará una solicitud, y Reset se moverá al siguiente en el tiempo. Un cliente que espera hasta Reset y luego envía un lote, recibirá de nuevo 429, por lo tanto, es más fiable ir de una solicitud en una o almacenar en caché las respuestas en tu lado.
- Una solicitud rechazada (429) no consume cuota y no desplaza la ventana: el contador se repone solo con solicitudes exitosas.
- X-RateLimit-Origin-Limit y X-RateLimit-Origin-Remaining: solo aparecen cuando la solicitud ha pasado por una entrada de la lista de orígenes permitidos, y muestran la parte asignada específicamente a esa entrada. El rechazo por esta parte también es 429, y en el texto se nombra qué entrada se ha agotado.
X-Subscription-Status y X-Subscription-Grace-Ends: solo aparecen cuando el período pagado ya ha terminado, y el período de gracia de 3 días aún está en curso (X-Subscription-Status: grace). Las solicitudes se atienden según tu tarifa hasta el momento indicado en X-Subscription-Grace-Ends, después de él, la respuesta es 402 SUBSCRIPTION_EXPIRED. Si tu cliente registra los encabezados, esta es la señal más temprana de que es hora de renovar el plan.
X-Request-Id: identificador de la solicitud, 32 caracteres hexadecimales; nómbralo al contactar con soporte

Cuánto se ha gastado ya: tres maneras

Puedes verificar el saldo actual de créditos de tres maneras, desde la más rápida hasta la más detallada:

En cada respuesta: los encabezados X-Credits-Remaining / X-Credits-Used / X-Credits-Limit se devuelven en CUALQUIER solicitud (incluso en caso de error). No necesitas llamar a nada adicional, el saldo siempre está a la vista.
Con una solicitud separada: GET /v1/keys/usage con tu X-Api-Key devuelve credits (used / remaining / limit / reset), usage (solicitudes por today / week / month) y los 20 endpoints principales de los últimos 30 días. Una sola llamada, sin una clave de administrador separada.
En el panel de control: api.astroway.info/dashboard/billing muestra el saldo, el gráfico de uso y el desglose por endpoints en tiempo real.

curl https://api.astroway.info/v1/keys/usage \
  -H "X-Api-Key: $AW_KEY"

Almacenamiento en caché

Las solicitudes idénticas realizadas en un plazo de 5 minutos se devuelven desde la caché sin consumir créditos. Este es un encabezado separado:

X-Cache: HIT
X-Credits-Used: 0

Qué se considera “idéntico”:

El mismo endpoint
El mismo cuerpo JSON (byte a byte después de la normalización de espacios)
La misma clave API

Esto es seguro, ya que todos los endpoints son deterministas: la misma entrada siempre produce la misma salida.

Streaming y webhooks

Streaming (`/stream/*`)

Los 10 endpoints de streaming se tarifan como Nivel 1: 10 créditos por llamada. Cada llamada recalcula las posiciones de los planetas, por lo tanto, es un cálculo completo, no una búsqueda en caché; no hay una tarifa “más barata” separada por tick.

Cada respuesta contiene dos campos para una consulta económica:

tickSeconds: intervalo de consulta recomendado;
nextEventAt: cuándo cambiará el estado la próxima vez.

Consultar con más frecuencia que tickSeconds es quemar créditos inútilmente: el estado no cambiará hasta nextEventAt.

Webhooks (`/webhooks/*`)

Las operaciones CRUD de gestión de suscripciones (/webhooks/subscribe, lista, ver, eliminar, /test) cuestan Nivel 1: 10 créditos cada una. Estas son llamadas poco frecuentes.

La entrega de eventos (servidor → tu URL) no se tarifa: los créditos se deducen solo por las llamadas CRUD de gestión. Se admiten 12 tipos de eventos (report-ready, transit-alert, eclipse-alert, dasha-change, sign-ingress, etc.).

Los webhooks están disponibles a partir del plan Pro y superiores.

Qué hacer al exceder los límites

`402 Payment Required`: créditos agotados

{
  "error": {
    "code": "credits_exhausted",
    "message": "Monthly credit budget exhausted. Upgrade plan or wait for reset.",
    "credits_remaining": 0,
    "credits_reset": "2026-05-01T00:00:00Z",
    "upgrade_url": "https://api.astroway.info/dashboard/billing"
  }
}

Opciones:

Actualizar plan: recibes inmediatamente un nuevo presupuesto
Overage (Starter/Pro): se activa automáticamente, si no está desactivado en la configuración
Esperar el restablecimiento (Free): el día 1 del mes siguiente

`429 Too Many Requests`: RPM excedido

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry after 12 seconds.",
    "retry_after_seconds": 12
  }
}

El encabezado Retry-After: 12 es un encabezado HTTP estándar, tu cliente HTTP debería entenderlo.

Manejo correcto:

async function callWithRetry(endpoint: string, body: object) {
  const response = await fetch(endpoint, {
    method: 'POST',
    headers: { 'X-Api-Key': key, 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  });

  if (response.status === 429) {
    const retryAfter = Number(response.headers.get('Retry-After') ?? 1);
    await new Promise((r) => setTimeout(r, retryAfter * 1000));
    return callWithRetry(endpoint, body);
  }

  return response.json();
}

Estimación del presupuesto por adelantado

Antes de la integración, estima cuántos créditos necesitas al mes:

monthly_credits = daily_active_users × calls_per_user × avg_cost_per_call × 30

Ejemplo: aplicación con 500 DAU, cada usuario realiza 3 cálculos de cartas + 1 sinastría al día:

500 × (3 × 20 + 1 × 50) × 30 = 500 × 110 × 30 = 1,650,000 credits/mo
→ Enterprise (custom)

Calculadora de presupuesto - en la página Tarifas.

Errores: guía completa de códigos de error
Idempotencia: cómo realizar solicitudes repetidas de forma segura

¿Útil?

Sugerir edición

Última actualización: 5 oct 2026

// Página anterior

Gematría y los 72 nombres

Siguiente página //

Coste por endpoint