Rate Limit

API 요청 제한과 대처 방법을 알아보세요. 모든 요청은 플랜의 시간당 쿼터에 포함되며, 응답 헤더를 통해 실시간으로 사용량을 확인할 수 있습니다.

인증 설정은 인증 문서를 참고하세요.

플랜별 제한

플랜	요청/시간	포스트/월	블로그
Free	60	누적 10	1
Starter ($9)	300	15	1
Creator ($29)	1,000	50	3
Scale ($79)	10,000	200	5
Enterprise	협의	협의	협의

전체 기능 비교는 플랜을 참고하세요.

응답 헤더

모든 API 응답에 rate limit 헤더가 포함됩니다:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 142
X-RateLimit-Reset: 1711324800

X-RateLimit-Limit — 플랜의 시간당 제한
X-RateLimit-Remaining — 현재 윈도우에서 남은 요청 수
X-RateLimit-Reset — 윈도우가 리셋되는 Unix 타임스탬프

코드에서 헤더 읽기

const res = await fetch('https://api.postlark.ai/v1/posts', {
  headers: { Authorization: 'Bearer pk_live_xxxxxxxxxxxx' },
});

const remaining = parseInt(res.headers.get('X-RateLimit-Remaining') ?? '0', 10);
const resetAt = parseInt(res.headers.get('X-RateLimit-Reset') ?? '0', 10);

if (remaining < 10) {
  const waitMs = (resetAt * 1000) - Date.now();
  console.log(`쿼터가 부족합니다. ${Math.ceil(waitMs / 1000)}초 후 리셋됩니다.`);
}

제한 초과 시

시간당 제한을 초과하면 429 Too Many Requests가 반환됩니다:

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Limit: 60 requests/hour.",
  "retry_after": 1823
}

retry_after 초만큼 대기 후 재시도하세요.

포스트 팩 (Starter+)

월간 포스트 제한을 초과할 경우, 포스트 팩을 추가 구매할 수 있습니다:

50 포스트 — $12 (만료 없음)
200 포스트 — $29 (만료 없음)

월간 쿼터가 먼저 소진되고, 초과분은 팩에서 차감됩니다. 자세한 가격과 구매 방법은 플랜을 참고하세요.