Créditos e limites

AstroWay utiliza um modelo de crédito em vez de um simples contador de pedidos.

Obtém uma chave API em 60 segundos

aw_test_demo_aaaa1111

Registar - grátis→

Isto é mais justo: endpoints leves (/planets) custam 10 créditos, os pesados (/rectification) custam 500.

Dois tipos de limites

1. Orçamento diário/mensal de créditos

A quantidade de créditos por mês depende do plano:

Plano	Créditos/mês	Limite diário
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

Assim que os créditos se esgotam, os pedidos subsequentes retornam 402 Payment Required (Free) ou ativam a faturação de overage (Indie+).

2. Limite de taxa (pedidos por minuto)

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

O limite de taxa é uma janela deslizante. Se fizeste 120 pedidos em 10 segundos, nos próximos 50 segundos com essa chave, receberás 429.

Dica

O limite de taxa e o orçamento de créditos são independentes. Podes ter créditos, mas não passar o limite de taxa. E vice-versa.

Se uma chave tem uma lista de origens permitidas, cada entrada da lista recebe a sua quota deste limite: o limite da chave é dividido pelo número de entradas, arredondado para cima. Um único site com um widget incorporado não pode, por causa disto, consumir a quota pela qual o proprietário da chave paga, enquanto os seus outros domínios permanecem funcionais. O limite total da chave não aumenta: as quotas dividem-no, não se somam a ele.

O contador é mantido por entrada, e não pelo host que fez o pedido. A entrada *.example.com é um único contador para todos os subdomínios, caso contrário, a restrição seria contornada inventando um novo subdomínio para cada pedido. Quando há uma única entrada na lista, a quota é igual ao limite e nada muda.

3. Endpoints públicos (sem chave)

14 dicionários de referência /v1/reference/* (signs, planets, houses, aspects, elements, modalities, polarities, dignities, decans, nakshatras, lots, asteroids, zodiac-systems, glyphs) são servidos publicamente, sem X-Api-Key e custam 0 créditos. O limite é de 30 pedidos/hora de um único IP. Estes mesmos dados são expostos como Recursos MCP astroway://reference/<slug> para agentes LLM.

O mesmo limite aplica-se aos restantes namespaces públicos: /v1/public/*, /v1/embed/*, /v1/i18n/*.

Quota para renderização no servidor

30 pedidos por hora são calculados para o navegador: cada visitante traz o seu próprio IP e a sua própria quota. No entanto, se os pedidos forem feitos pelo teu servidor (plugin WordPress, SSR, aquecimento de cache), um único endereço serve todos os visitantes e esgota o limite em algumas recargas de página.

Para este caso, envia o cabeçalho X-AstroWay-Site-URL com o endereço do site:

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

Modo	Limite
Sem cabeçalho	30 pedidos / hora por IP; widgets /v1/embed/* têm 120 / hora por IP separados
Com cabeçalho	300 pedidos / hora por site, teto de 600 / hora por IP

O cabeçalho é permitido em CORS e não são credenciais, por isso o teto por IP permanece: não importa quantos domínios sejam nomeados de um único endereço, um total de não mais de 600 pedidos por hora sairão de lá. Ambos os contadores são necessários simultaneamente: o contador do site é ativado quando um site acede a partir de vários endereços (CDN, balanceador), o contador de IP é ativado quando muitos nomes vêm de um único endereço.

Uma chamada nem sempre é uma unidade. Um endpoint público pesado consome mais do mesmo cesto, e não recebe um separado. POST /v1/public/synastry custa 3, porque são dois mapas e uma matriz de aspetos de 45 células: o teto prático para ele é 10 por hora de um endereço não declarado, 100 para um site declarado e 200 por endereço. Tudo o resto custa 1. Quando uma chamada custa mais de uma unidade, a resposta indica isso no cabeçalho X-RateLimit-Cost, e uma chamada que custa mais do que o que resta no cesto é rejeitada, e não entra em saldo negativo.

Qual contador está mais apertado no momento é indicado pelo cabeçalho da resposta X-RateLimit-Scope (ip ou site). Os restantes cabeçalhos X-RateLimit-* descrevem apenas esse, ou seja, apenas um dos dois contadores. O segundo é visível em X-RateLimit-Counters:

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

O formato é scope=restante/limite separado por vírgula. O cabeçalho só aparece quando há realmente dois contadores: uma chamada anónima com X-AstroWay-Site-URL. Uma chamada com uma chave paga é contada pela tua chave e pela tua tarifa, lá há apenas um contador e não há cabeçalho. Lê-o se estiveres a renderizar a partir do servidor vários domínios de um único endereço: o cesto do site de cada domínio é seu, mas o teto por IP é partilhado, e é ele que é atingido primeiro.

Armazena em cache as respostas do teu lado: o horóscopo diário não muda durante o dia, e uma cache até à meia-noite resolve completamente a questão do limite.

Chave paga em endpoints públicos. /v1/public/* e /v1/embed/* funcionam sem chave, mas se a passares (X-Api-Key), o pedido é contado pela tua tarifa, e não pela quota anónima, e a resposta não tem marca d’água gratuita. Isto faz sentido para renderização server-side: uma máquina acede por todos os visitantes, e 300/hora anónimos é pouco para ela.

Tabela de custos

Uma tabela completa e transparente com todos os 771+ endpoints e os seus custos está na página Custo dos endpoints. DivineAPI/AstrologyAPI/Prokerala não publicam tal tabela. Uma referência rápida:

Nível	Créditos	Tempo típico	Exemplos
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	alguns s	/rectification/trutine
6	500	até 120 s	/rectification

Cabeçalhos de resposta

Cada resposta contém:

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: quanto foi debitado por este pedido
• X-Credits-Remaining: saldo restante no orçamento mensal
• X-Credits-Limit: orçamento total de créditos por mês (por plano)
• X-Credits-Reset: data ISO-8601 de atualização do saldo
• X-RateLimit-*: estado atual da janela deslizante (formato padrão)
  • X-RateLimit-Scope: qual contador está mais apertado no momento: ip, site ou key. O valor key significa que o pedido foi contado pela tua chave e pelo limite da tua tarifa, e não pela quota anónima.
  • X-RateLimit-Counters: num endpoint público, chamado com X-AstroWay-Site-URL, todos os contadores pelos quais o pedido foi contado, no formato scope=restante/limite. Os cabeçalhos acima descrevem apenas o mais apertado.
  • X-RateLimit-Reset: o momento em que o pedido mais antigo sairá da janela, ou seja, quando um slot for libertado. Este não é o tempo de abertura total do bucket: depois dele, um pedido passará, e Reset será deslocado para o próximo no tempo. Um cliente que espera até Reset e depois envia um lote, receberá novamente 429, por isso é mais fiável fazer um pedido de cada vez ou armazenar em cache as respostas do teu lado.
  • Um pedido rejeitado (429) não consome quota e não desloca a janela: o contador é preenchido apenas por pedidos bem-sucedidos.
  • X-RateLimit-Origin-Limit e X-RateLimit-Origin-Remaining: aparecem apenas quando o pedido passou por uma entrada da lista de origens permitidas, e mostram a quota atribuída especificamente a essa entrada. Uma recusa por esta quota também é 429, e o texto indica qual entrada foi esgotada.
• X-Subscription-Status e X-Subscription-Grace-Ends: aparecem apenas quando o período pago já terminou, e o período de carência de 3 dias ainda está em curso (X-Subscription-Status: grace). Os pedidos são servidos de acordo com a tua tarifa até ao momento em X-Subscription-Grace-Ends, após o qual a resposta é 402 SUBSCRIPTION_EXPIRED. Se o teu cliente regista os cabeçalhos, este é o sinal mais precoce de que é hora de renovar o plano.
• X-Request-Id: identificador do pedido, 32 caracteres hexadecimais; menciona-o ao contactar o suporte

Quanto já foi gasto: três maneiras

Podes verificar o saldo atual de créditos de três maneiras - da mais rápida à mais detalhada:

1. Em cada resposta: os cabeçalhos X-Credits-Remaining / X-Credits-Used / X-Credits-Limit são retornados em qualquer pedido (mesmo em caso de erro). Não precisas de chamar nada adicionalmente - o saldo está sempre visível.
2. Com um pedido separado: GET /v1/keys/usage com a tua X-Api-Key retorna credits (used / remaining / limit / reset), usage (pedidos por today / week / month) e os 20 principais endpoints dos últimos 30 dias. Uma única chamada, sem uma chave de administrador separada.
3. No dashboard: api.astroway.info/dashboard/billing mostra o saldo, o gráfico de uso e a discriminação por endpoints em tempo real.

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

Dica

Ao contrário da maioria das APIs (Anthropic, OpenAI), AstroWay retorna o saldo restante diretamente no cabeçalho de cada resposta (X-Credits-Remaining) - não precisas de ir ao dashboard ou a uma API de uso separada para saber quanto resta.

Cache

Pedidos idênticos dentro de 5 minutos são retornados da cache sem débito de créditos. Este é um cabeçalho separado:

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

O que é considerado “idêntico”:

• O mesmo endpoint
• O mesmo corpo JSON (byte a byte após normalização de espaços)
• A mesma chave API

Isto é seguro, porque todos os endpoints são determinísticos - o mesmo input sempre dá o mesmo output.

Streaming e webhooks

Streaming (/stream/*)

10 endpoints de stream são tarifados como Nível 1: 10 créditos por chamada. Cada chamada recalcula as posições dos planetas, por isso é um cálculo completo, e não uma pesquisa em cache - não há uma taxa “mais barata” separada por tick.

Cada resposta contém dois campos para polling económico:

• tickSeconds: intervalo de polling recomendado;
• nextEventAt: quando o estado mudará da próxima vez.

Fazer polling mais frequentemente do que tickSeconds é queimar créditos em vão: o estado não mudará até nextEventAt.

Cuidado

Exemplo de orçamento: um stream, com polling a cada 60 s = 1 440 chamadas/dia × 10 créditos = 14 400 créditos/dia. No Indie (50 000/mês), isto são ~3.5 dias de um stream. Para streaming contínuo - Starter+.

Webhooks (/webhooks/*)

As operações CRUD de gestão de subscrição (/webhooks/subscribe, listar, ver, eliminar, /test) custam Nível 1: 10 créditos cada. Estas são chamadas raras.

A entrega de eventos (servidor → o teu URL) não é tarifada: os créditos são debitados apenas pelas chamadas CRUD de gestão. São suportados 12 tipos de eventos (report-ready, transit-alert, eclipse-alert, dasha-change, sign-ingress, etc.).

Os webhooks estão disponíveis a partir do plano Pro e superior.

O que fazer ao exceder os limites

402 Payment Required: créditos esgotados

{
  "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"
  }
}

Opções:

• Upgrade de plano: recebes imediatamente um novo orçamento
• Overage (Starter/Pro): ativado automaticamente, se não desativado nas configurações
• Esperar pelo reset (Free): dia 1 do mês seguinte

429 Too Many Requests: RPM excedido

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

O cabeçalho Retry-After: 12 é um cabeçalho HTTP padrão, o teu cliente HTTP deve compreendê-lo.

Tratamento correto:

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();
}

Cuidado

Não faças backoff exponencial sem um limite - Retry-After na resposta já contém o número exato. Confia nele.

Estimativa de orçamento antecipada

Antes da integração, estima quantos créditos precisas por mês:

monthly_credits = daily_active_users × calls_per_user × avg_cost_per_call × 30

Exemplo: uma aplicação com 500 DAU, cada utilizador faz 3 cálculos de mapas + 1 sinastria por dia:

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

A calculadora de orçamento está na página Tarifas.

A seguir

• Erros: referência completa de códigos de erro
• Idempotência: como fazer pedidos repetidos de forma segura