크레딧 및 한도

AstroWay는 단순한 요청 카운터 대신 크레딧 모델을 사용합니다.

더 공정합니다: 가벼운 엔드포인트 (/planets)는 10 크레딧, 무거운 엔드포인트 (/rectification)는 500 크레딧입니다.

두 가지 유형의 제한

1. 일일/월간 크레딧 예산

월간 크레딧 수는 플랜에 따라 다릅니다:

플랜	월간 크레딧	일일 제한
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

크레딧이 소진되면 다음 요청은 402 Payment Required (Free)를 반환하거나 초과 사용 요금 청구 (Indie+)를 시작합니다.

2. Rate limit (분당 요청 수)

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

Rate limit은 슬라이딩 윈도우 방식입니다. 10초 동안 120개의 요청을 보냈다면, 해당 키에 대한 다음 50초 동안은 429 응답을 받게 됩니다.

키에 허용된 출처 목록이 있는 경우, 목록의 각 항목은 이 제한의 자체 할당량을 받습니다: 키 제한을 항목 수로 나눈 후 올림합니다. 내장 위젯이 있는 한 사이트가 키 소유자가 지불하는 할당량을 모두 소진하여 다른 도메인이 작동하지 않게 되는 것을 방지합니다. 키의 전체 제한은 증가하지 않습니다: 할당량은 전체 제한을 나누는 것이지 추가되는 것이 아닙니다.

카운터는 들어오는 호스트가 아니라 항목별로 유지됩니다. *.example.com 항목은 모든 서브도메인에 대해 하나의 카운터입니다. 그렇지 않으면 요청마다 새로운 서브도메인을 만들어 제한을 우회할 수 있습니다. 목록에 항목이 하나만 있는 경우, 할당량은 제한과 동일하며 아무것도 변경되지 않습니다.

3. 공개 엔드포인트 (키 없음)

14개의 참조 사전 /v1/reference/* (signs, planets, houses, aspects, elements, modalities, polarities, dignities, decans, nakshatras, lots, asteroids, zodiac-systems, glyphs)는 공개적으로 X-Api-Key 없이 제공되며 0 크레딧입니다. 제한은 단일 IP당 시간당 30회 요청입니다. 동일한 데이터는 LLM 에이전트를 위한 MCP 리소스 astroway://reference/<slug>로 노출됩니다.

동일한 제한이 나머지 공개 네임스페이스 /v1/public/*, /v1/embed/*, /v1/i18n/*에도 적용됩니다.

서버 측 렌더링 할당량

시간당 30회 요청은 브라우저를 위해 설계되었습니다: 각 방문자는 자체 IP와 자체 할당량을 가져옵니다. 그러나 서버 (WordPress 플러그인, SSR, 캐시 워밍업)가 요청을 하는 경우, 단일 주소가 모든 방문자를 대신하여 페이지를 몇 번 새로 고치면 제한이 소진됩니다.

이 경우, 사이트 주소와 함께 X-AstroWay-Site-URL 헤더를 보내세요:

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

모드	제한
헤더 없음	IP당 시간당 30회 요청; 위젯 `/v1/embed/*`는 IP당 시간당 120회 별도
헤더 포함	사이트당 시간당 300회 요청, IP당 시간당 600회 상한

헤더는 CORS에서 허용되며 자격 증명이 아니므로 IP당 상한은 유지됩니다: 단일 주소에서 아무리 많은 도메인을 지정하더라도 총 시간당 600회 요청을 초과할 수 없습니다. 두 카운터는 동시에 필요합니다: 사이트 카운터는 단일 사이트가 여러 주소 (CDN, 로드 밸런서)에서 요청할 때 작동하고, IP 카운터는 단일 주소에서 여러 이름이 올 때 작동합니다.

단일 호출이 항상 단일 단위는 아닙니다. 무거운 공개 엔드포인트는 별도의 할당량을 받는 것이 아니라 동일한 버킷에서 더 많은 것을 소비합니다. POST /v1/public/synastry는 두 개의 차트와 45개 셀의 어스펙트 매트릭스이므로 3 크레딧이 소요됩니다: 이에 대한 실제 상한은 미신고 주소에서 시간당 10회, 신고된 사이트에서 100회, 주소당 200회입니다. 다른 모든 것은 1 크레딧입니다. 호출 비용이 1단위보다 많으면 응답은 X-RateLimit-Cost 헤더에 이를 명시하며, 버킷에 남은 것보다 비용이 더 많이 드는 호출은 거부되고 마이너스로 가지 않습니다.

현재 가장 엄격한 카운터는 응답 헤더 X-RateLimit-Scope (ip 또는 site)에 명시됩니다. 나머지 X-RateLimit-* 헤더는 해당 카운터, 즉 두 카운터 중 하나만 설명합니다. 두 번째는 X-RateLimit-Counters에서 볼 수 있습니다:

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

형식은 쉼표로 구분된 scope=남은/제한입니다. 헤더는 카운터가 실제로 두 개인 경우에만 제공됩니다: X-AstroWay-Site-URL이 있는 익명 호출. 유료 키가 있는 호출은 키와 요금제에 따라 계산되며, 이 경우 카운터는 하나이고 헤더는 없습니다. 단일 주소에서 여러 도메인을 서버 측 렌더링하는 경우 이를 읽으세요: 각 도메인의 사이트 버킷은 자체적이지만 IP당 상한은 공유되며, 이 상한이 먼저 도달됩니다.

응답을 자체적으로 캐시하세요: 일일 운세는 하루 동안 변경되지 않으며, 자정까지 캐시하면 제한 문제를 완전히 해결할 수 있습니다.

공개 엔드포인트의 유료 키. /v1/public/* 및 /v1/embed/*는 키 없이 작동하지만, 키 (X-Api-Key)를 전달하면 요청은 익명 할당량이 아닌 요금제에 따라 계산되며 응답에 무료 워터마크가 없습니다. 이는 서버 측 렌더링에 유용합니다: 단일 머신이 모든 방문자를 대신하여 요청하며, 익명 시간당 300회는 충분하지 않습니다.

비용표

모든 771+ 엔드포인트와 비용에 대한 완전하고 투명한 표는 엔드포인트 비용 페이지에 있습니다. DivineAPI/AstrologyAPI/Prokerala는 이러한 표를 게시하지 않습니다. 간략한 참조:

티어	크레딧	일반적인 시간	예시
1	10	< 50 мс	`/planets`, `/moon-voc`, `/iching`
2	20	50–200 мс	`/chart`, `/harmonics`, `/horary`
3	50	200–500 мс	`/synastry`, `/progressions`, `/acg`
4	100	> 500 мс	`/transit-calendar`, `/forecast-calendar`
5	250	몇 초	`/rectification/trutine`
6	500	최대 120초	`/rectification`

응답 헤더

각 응답에는 다음이 포함됩니다:

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: 이 요청에 대해 사용된 크레딧 수
X-Credits-Remaining: 월간 예산에 남은 크레딧
X-Credits-Limit: 월간 전체 크레딧 예산 (플랜에 따라)
X-Credits-Reset: 잔액 갱신 ISO-8601 날짜
X-RateLimit-*: 슬라이딩 윈도우의 현재 상태 (표준 형식)
- X-RateLimit-Scope: 현재 가장 엄격한 카운터: ip, site 또는 key. key 값은 요청이 익명 할당량이 아닌 키와 요금제 제한에 따라 계산되었음을 의미합니다.
- X-RateLimit-Counters: X-AstroWay-Site-URL로 호출된 공개 엔드포인트에서, 요청이 계산된 모든 카운터는 scope=남은/제한 형식으로 표시됩니다. 위의 헤더는 가장 엄격한 카운터만 설명합니다.
- X-RateLimit-Reset: 가장 오래된 요청이 윈도우에서 제거되는 시점, 즉 하나의 슬롯이 비워지는 시점입니다. 이는 버킷이 완전히 열리는 시간이 아닙니다: 그 후 하나의 요청이 통과하면 Reset은 다음 시간으로 이동합니다. Reset까지 기다렸다가 일괄 요청을 보내는 클라이언트는 다시 429를 받게 되므로, 한 번에 하나의 요청을 보내거나 응답을 자체적으로 캐시하는 것이 더 안정적입니다.
- 거부된 요청 (429)은 할당량을 소비하지 않으며 윈도우를 이동시키지 않습니다: 카운터는 성공적인 요청으로만 채워집니다.
- X-RateLimit-Origin-Limit 및 X-RateLimit-Origin-Remaining: 요청이 허용된 출처 목록의 항목을 통해 통과했을 때만 제공되며, 해당 항목에 할당된 할당량을 보여줍니다. 이 할당량으로 인한 거부도 429이며, 텍스트에 어떤 항목이 소진되었는지 명시됩니다.
X-Subscription-Status 및 X-Subscription-Grace-Ends: 유료 기간이 이미 종료되었지만 3일간의 유예 기간이 아직 진행 중일 때만 제공됩니다 (X-Subscription-Status: grace). 요청은 X-Subscription-Grace-Ends에 명시된 시점까지 요금제에 따라 처리되며, 그 이후에는 402 SUBSCRIPTION_EXPIRED 응답을 받게 됩니다. 클라이언트가 헤더를 로깅하는 경우, 이는 플랜을 갱신해야 할 가장 빠른 신호입니다.
X-Request-Id: 요청 식별자, 32개의 16진수 문자; 지원팀에 문의할 때 이를 언급하세요.

이미 사용된 금액: 세 가지 방법

현재 크레딧 잔액은 가장 빠른 방법부터 가장 상세한 방법까지 세 가지 방법으로 확인할 수 있습니다:

모든 응답에서: X-Credits-Remaining / X-Credits-Used / X-Credits-Limit 헤더는 모든 요청 (오류에도 불구하고)에 반환됩니다. 추가로 호출할 필요가 없습니다 - 잔액은 항상 눈앞에 있습니다.
별도 요청으로: X-Api-Key와 함께 GET /v1/keys/usage는 credits (used / remaining / limit / reset), usage (오늘 / 주 / 월별 요청 수) 및 지난 30일간의 상위 20개 엔드포인트를 반환합니다. 단일 호출이며 별도의 관리자 키가 필요하지 않습니다.
대시보드에서: api.astroway.info/dashboard/billing은 실시간으로 잔액, 사용량 그래프 및 엔드포인트별 분석을 보여줍니다.

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

캐싱

5분 이내의 동일한 요청은 크레딧 차감 없이 캐시에서 반환됩니다. 이는 별도의 헤더입니다:

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

“동일”하다고 간주되는 것:

동일한 엔드포인트
동일한 JSON 본문 (공백 정규화 후 바이트 단위로)
동일한 API 키

모든 엔드포인트는 결정론적이므로 안전합니다 - 동일한 입력은 항상 동일한 출력을 제공합니다.

스트리밍 및 웹훅

스트리밍 (`/stream/*`)

10개의 스트림 엔드포인트는 티어 1: 호출당 10 크레딧으로 요금이 부과됩니다. 각 호출은 행성 위치를 다시 계산하므로, 이는 캐시된 조회 대신 완전한 계산입니다 - 틱당 별도의 “더 저렴한” 요금은 없습니다.

각 응답에는 효율적인 폴링을 위한 두 가지 필드가 포함됩니다:

tickSeconds: 권장 폴링 간격;
nextEventAt: 다음 상태 변경 시점.

tickSeconds보다 더 자주 폴링하는 것은 크레딧을 낭비하는 것입니다: nextEventAt까지 상태는 변경되지 않습니다.

웹훅 (`/webhooks/*`)

구독 관리 CRUD 작업 (/webhooks/subscribe, 목록, 보기, 삭제, /test)은 각각 티어 1: 10 크레딧이 소요됩니다. 이는 드문 호출입니다.

이벤트 전달 (서버 → 귀하의 URL)은 요금이 부과되지 않습니다: 크레딧은 관리 CRUD 호출에 대해서만 차감됩니다. 12가지 이벤트 유형 (report-ready, transit-alert, eclipse-alert, dasha-change, sign-ingress 등)이 지원됩니다.

웹훅은 Pro 플랜 이상에서 사용할 수 있습니다.

제한 초과 시 대처 방법

`402 Payment Required`: 크레딧 소진

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

옵션:

플랜 업그레이드: 즉시 새로운 예산을 받습니다
초과 사용 (Starter/Pro): 설정에서 비활성화하지 않은 경우 자동으로 활성화됩니다
재설정 대기 (Free): 다음 달 1일

`429 Too Many Requests`: RPM 초과

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

Retry-After: 12 헤더는 표준 HTTP 헤더이며, HTTP 클라이언트는 이를 이해해야 합니다.

올바른 처리:

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

예산 사전 평가

통합 전에 월간 필요한 크레딧 수를 추정하세요:

monthly_credits = daily_active_users × calls_per_user × avg_cost_per_call × 30

예시: 500 DAU 앱, 각 사용자가 하루에 3개의 차트 계산 + 1개의 시나스트리 계산을 수행:

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

예산 계산기는 요금제 페이지에 있습니다.

오류: 전체 오류 코드 참조
멱등성: 안전하게 반복 요청하는 방법

도움이 되었나요?

수정 제안하기

마지막 업데이트: 2026. 10. 5.