Credit và giới hạn

AstroWay sử dụng mô hình tín dụng thay vì chỉ đếm số yêu cầu đơn giản.

Điều này công bằng hơn: các endpoint nhẹ (/planets) tốn 10 tín dụng, các endpoint nặng (/rectification) tốn 500.

Hai loại giới hạn

1. Ngân sách tín dụng hàng ngày/hàng tháng

Số lượng tín dụng mỗi tháng phụ thuộc vào gói:

Gói	Tín dụng/tháng	Giới hạn hàng ngày
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	Tùy chỉnh	Tùy chỉnh

Ngay khi tín dụng cạn kiệt - các yêu cầu tiếp theo sẽ trả về 402 Payment Required (Free) hoặc kích hoạt thanh toán vượt mức (overage-billing) (Indie+).

2. Giới hạn tốc độ (số yêu cầu mỗi phút)

Gói	RPM
Free	10 req/min
Indie	30 req/min
Starter	120 req/min
Pro	400 req/min
Business	1.000 req/min
Enterprise	Tùy chỉnh

Giới hạn tốc độ là cửa sổ trượt (sliding window). Nếu bạn gửi 120 yêu cầu trong 10 giây, 50 giây tiếp theo trên khóa này sẽ là 429.

Nếu một khóa có danh sách các nguồn gốc được phép, mỗi mục trong danh sách sẽ nhận được một phần của giới hạn này: giới hạn của khóa được chia cho số lượng mục, làm tròn lên. Một trang web với widget nhúng không thể vì điều này mà tiêu tốn hết hạn mức mà chủ khóa đã trả tiền, trong khi các tên miền khác của anh ta vẫn hoạt động. Giới hạn tổng thể của khóa không tăng: các phần hạn mức chia sẻ nó, chứ không cộng thêm vào nó.

Bộ đếm được tính theo mục, chứ không phải theo máy chủ (host) đến. Mục *.example.com là một bộ đếm cho tất cả các tên miền con, nếu không thì giới hạn có thể bị vượt qua bằng cách tạo ra một tên miền con mới cho mỗi yêu cầu. Khi trong danh sách chỉ có một mục, phần hạn mức bằng với giới hạn và không có gì thay đổi.

3. Các endpoint công khai (không cần khóa)

14 từ điển tham chiếu /v1/reference/* (signs, planets, houses, aspects, elements, modalities, polarities, dignities, decans, nakshatras, lots, asteroids, zodiac-systems, glyphs) được phục vụ công khai, không cần X-Api-Key và tốn 0 tín dụng. Giới hạn là 30 yêu cầu / giờ từ một IP. Dữ liệu này cũng được cung cấp dưới dạng Tài nguyên MCP astroway://reference/<slug> cho các tác nhân LLM.

Cùng một giới hạn áp dụng cho các namespace công khai còn lại: /v1/public/*, /v1/embed/*, /v1/i18n/*.

Hạn mức cho việc render trên máy chủ

30 yêu cầu mỗi giờ được tính cho trình duyệt: mỗi khách truy cập mang theo IP riêng và hạn mức riêng. Nếu máy chủ của bạn thực hiện các yêu cầu (plugin WordPress, SSR, làm nóng cache), một địa chỉ sẽ thay mặt tất cả khách truy cập và làm cạn kiệt giới hạn chỉ sau vài lần tải lại trang.

Trong trường hợp này, hãy gửi tiêu đề X-AstroWay-Site-URL với địa chỉ trang web của bạn:

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

Chế độ	Giới hạn
Không có tiêu đề	30 yêu cầu / giờ trên mỗi IP; các widget `/v1/embed/*` có giới hạn riêng là 120 / giờ trên mỗi IP
Với tiêu đề	300 yêu cầu / giờ cho mỗi trang web, giới hạn tối đa 600 / giờ cho mỗi IP

Tiêu đề được phép trong CORS và không phải là thông tin xác thực, vì vậy giới hạn tối đa trên IP vẫn còn: dù bạn khai báo bao nhiêu tên miền từ một địa chỉ, tổng cộng sẽ không có nhiều hơn 600 yêu cầu mỗi giờ từ đó. Cả hai bộ đếm đều cần thiết đồng thời: bộ đếm trang web hoạt động khi một trang web truy cập từ nhiều địa chỉ (CDN, bộ cân bằng tải), bộ đếm IP hoạt động khi nhiều tên miền đến từ một địa chỉ.

Một lệnh gọi không phải lúc nào cũng là một đơn vị. Một endpoint công khai nặng sẽ tiêu tốn nhiều hơn từ cùng một giỏ, chứ không nhận được một giỏ riêng. POST /v1/public/synastry tốn 3, vì nó bao gồm hai biểu đồ và một ma trận khía cạnh 45 ô: giới hạn thực tế cho nó là 10 mỗi giờ từ một địa chỉ không được khai báo, 100 cho một trang web đã khai báo và 200 cho một địa chỉ. Tất cả những thứ khác tốn 1. Khi một lệnh gọi tốn nhiều hơn một đơn vị, phản hồi sẽ cho biết điều này trong tiêu đề X-RateLimit-Cost, và một lệnh gọi tốn nhiều hơn số còn lại trong giỏ sẽ bị từ chối, chứ không bị âm.

Tiêu đề phản hồi X-RateLimit-Scope (ip hoặc site) cho biết bộ đếm nào hiện đang bị giới hạn chặt nhất. Các tiêu đề X-RateLimit-* còn lại chỉ mô tả bộ đếm đó, tức là chỉ một trong hai bộ đếm. Bộ đếm thứ hai được hiển thị trong X-RateLimit-Counters:

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

Định dạng là scope=còn lại/giới hạn được phân tách bằng dấu phẩy. Tiêu đề chỉ xuất hiện khi thực sự có hai bộ đếm: một lệnh gọi ẩn danh với X-AstroWay-Site-URL. Một lệnh gọi với khóa trả phí được tính theo khóa của bạn và theo gói của bạn, ở đó chỉ có một bộ đếm và không có tiêu đề. Hãy đọc nó nếu bạn render từ máy chủ nhiều tên miền từ cùng một địa chỉ: giỏ của trang web là riêng cho mỗi tên miền, nhưng giới hạn tối đa trên IP là chung, và đó là cái bị chạm trước tiên.

Hãy cache các phản hồi ở phía bạn: tử vi hàng ngày không thay đổi trong suốt một ngày, và việc cache cho đến nửa đêm sẽ giải quyết hoàn toàn vấn đề giới hạn.

Khóa trả phí trên các endpoint công khai. /v1/public/* và /v1/embed/* hoạt động mà không cần khóa, nhưng nếu bạn truyền khóa (X-Api-Key), yêu cầu được tính theo gói của bạn, chứ không phải theo hạn mức ẩn danh, và phản hồi không có hình mờ miễn phí. Điều này có ý nghĩa đối với việc render phía máy chủ (server-side render): một máy chủ truy cập thay mặt tất cả khách truy cập, và 300/giờ ẩn danh là không đủ cho nó.

Bảng chi phí

Bảng đầy đủ và minh bạch với tất cả 771+ endpoint và chi phí của chúng - trên trang Chi phí endpoint. DivineAPI/AstrologyAPI/Prokerala không công bố bảng như vậy. Hướng dẫn nhanh:

Cấp	Tín dụng	Thời gian điển hình	Ví dụ
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	vài giây	`/rectification/trutine`
6	500	lên đến 120 giây	`/rectification`

Tiêu đề phản hồi

Mỗi phản hồi chứa:

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: số tín dụng đã sử dụng cho yêu cầu này
X-Credits-Remaining: số tín dụng còn lại trong ngân sách hàng tháng
X-Credits-Limit: tổng ngân sách tín dụng hàng tháng (theo gói)
X-Credits-Reset: ngày ISO-8601 khi số dư được đặt lại
X-RateLimit-*: trạng thái hiện tại của cửa sổ trượt (định dạng chuẩn)
- X-RateLimit-Scope: bộ đếm nào hiện đang bị giới hạn chặt nhất: ip, site hoặc key. Giá trị key có nghĩa là yêu cầu được tính theo khóa của bạn và theo giới hạn gói của bạn, chứ không phải theo hạn mức ẩn danh.
- X-RateLimit-Counters: trên một endpoint công khai, được gọi với X-AstroWay-Site-URL, tất cả các bộ đếm mà yêu cầu được tính theo, ở định dạng scope=còn lại/giới hạn. Các tiêu đề trên chỉ mô tả bộ đếm bị giới hạn chặt nhất.
- X-RateLimit-Reset: thời điểm yêu cầu cũ nhất sẽ rơi ra khỏi cửa sổ, tức là khi một slot được giải phóng. Đây không phải là thời gian mở hoàn toàn của bucket: sau đó một yêu cầu sẽ được thực hiện, và Reset sẽ dịch chuyển đến yêu cầu tiếp theo theo thời gian. Một client chờ đến Reset rồi gửi một loạt yêu cầu sẽ lại nhận được 429, vì vậy an toàn hơn là gửi từng yêu cầu một hoặc cache các phản hồi ở phía bạn.
- Một yêu cầu bị từ chối (429) không tiêu tốn hạn mức và không làm dịch chuyển cửa sổ: bộ đếm chỉ được bổ sung bởi các yêu cầu thành công.
- X-RateLimit-Origin-Limit và X-RateLimit-Origin-Remaining: chỉ xuất hiện khi yêu cầu được thực hiện thông qua một mục trong danh sách các nguồn gốc được phép, và hiển thị phần hạn mức được phân bổ cho chính mục đó. Việc từ chối do phần hạn mức này cũng là 429, và trong văn bản sẽ nêu rõ mục nào đã cạn kiệt.
X-Subscription-Status và X-Subscription-Grace-Ends: chỉ xuất hiện khi thời gian đã thanh toán đã kết thúc, và thời gian ân hạn 3 ngày vẫn đang diễn ra (X-Subscription-Status: grace). Các yêu cầu được phục vụ theo gói của bạn cho đến thời điểm trong X-Subscription-Grace-Ends, sau đó phản hồi sẽ là 402 SUBSCRIPTION_EXPIRED. Nếu client của bạn ghi nhật ký các tiêu đề, đây là tín hiệu sớm nhất cho thấy đã đến lúc gia hạn gói.
X-Request-Id: mã định danh yêu cầu, 32 ký tự thập lục phân; hãy cung cấp nó khi liên hệ hỗ trợ

Đã sử dụng bao nhiêu: ba cách

Bạn có thể kiểm tra số dư tín dụng hiện tại bằng ba cách - từ nhanh nhất đến chi tiết nhất:

Trong mỗi phản hồi: các tiêu đề X-Credits-Remaining / X-Credits-Used / X-Credits-Limit được trả về cho bất kỳ yêu cầu nào (ngay cả khi có lỗi). Không cần gọi thêm gì cả - số dư luôn hiển thị rõ ràng.
Bằng một yêu cầu riêng: GET /v1/keys/usage với X-Api-Key của bạn trả về credits (đã sử dụng / còn lại / giới hạn / đặt lại), usage (số yêu cầu theo ngày / tuần / tháng) và 20 endpoint hàng đầu trong 30 ngày. Một lệnh gọi, không cần khóa admin riêng.
Trong bảng điều khiển: api.astroway.info/dashboard/billing hiển thị số dư, biểu đồ sử dụng và phân tích theo endpoint theo thời gian thực.

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

Cache

Các yêu cầu giống hệt nhau trong vòng 5 phút sẽ được trả về từ cache mà không bị trừ tín dụng. Đây là một tiêu đề riêng:

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

Điều gì được coi là “giống hệt”:

Cùng một endpoint
Cùng một JSON body (byte-by-byte sau khi chuẩn hóa khoảng trắng)
Cùng một khóa API

Điều này an toàn, vì tất cả các endpoint đều xác định - cùng một đầu vào luôn cho cùng một đầu ra.

Streaming và Webhook

Streaming (`/stream/*`)

10 endpoint stream được tính phí là Cấp 1: 10 tín dụng cho mỗi lệnh gọi. Mỗi lệnh gọi tính toán lại vị trí các hành tinh, vì vậy đây là một phép tính đầy đủ, chứ không phải là một tra cứu được cache - không có mức giá “rẻ hơn” riêng cho mỗi tick.

Mỗi phản hồi chứa hai trường để thăm dò tiết kiệm:

tickSeconds: khoảng thời gian thăm dò được khuyến nghị;
nextEventAt: khi trạng thái sẽ thay đổi lần tiếp theo.

Thăm dò thường xuyên hơn tickSeconds là lãng phí tín dụng: trạng thái sẽ không thay đổi cho đến nextEventAt.

Webhook (`/webhooks/*`)

Các thao tác CRUD quản lý đăng ký (/webhooks/subscribe, liệt kê, xem, xóa, /test) tốn Cấp 1: 10 tín dụng mỗi thao tác. Đây là các lệnh gọi hiếm khi xảy ra.

Việc gửi sự kiện (máy chủ → URL của bạn) không bị tính phí: tín dụng chỉ bị trừ cho các lệnh gọi CRUD quản lý. Hỗ trợ 12 loại sự kiện (report-ready, transit-alert, eclipse-alert, dasha-change, sign-ingress, v.v.).

Webhook có sẵn từ gói Pro trở lên.

Phải làm gì khi vượt quá giới hạn

`402 Payment Required`: hết tín dụng

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

Các lựa chọn:

Nâng cấp gói: bạn sẽ nhận được ngân sách mới ngay lập tức
Overage (Starter/Pro): tự động bật nếu không bị tắt trong cài đặt
Chờ đặt lại (Free): ngày 1 của tháng tiếp theo

`429 Too Many Requests`: vượt quá RPM

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

Tiêu đề Retry-After: 12 - là một tiêu đề HTTP chuẩn, client HTTP của bạn nên hiểu nó.

Xử lý đúng cách:

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

Ước tính ngân sách trước

Trước khi tích hợp, hãy ước tính bạn cần bao nhiêu tín dụng mỗi tháng:

monthly_credits = daily_active_users × calls_per_user × avg_cost_per_call × 30

Ví dụ: ứng dụng có 500 DAU, mỗi người dùng thực hiện 3 tính toán biểu đồ + 1 synastry mỗi ngày:

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

Công cụ tính ngân sách - trên trang Gói cước.

Lỗi: hướng dẫn đầy đủ về mã lỗi
Idempotency: cách thực hiện các yêu cầu lặp lại một cách an toàn

Hữu ích chứ?

Đề xuất chỉnh sửa

Cập nhật lần cuối: 11 thg 10, 2026

// Trước

Gematria và 72 danh xưng

Tiếp //

Chi phí theo endpoint