요청 한도 (Rate limit)

공개 API는 API 키마다 초당 1회(1 RPS) 로 제한해요.

규칙

항목	값
단위	API 키 1개당
한도	1 request / 1 second
적용 대상	인증이 필요한 엔드포인트 (현재 GET /v1/servers)
헬스 체크	/health, / 는 키 불필요 · 이 RPS와 별개

연속으로 1초 안에 같은 키로 두 번 이상 인증 시도하면 두 번째부터 거절돼요.
마지막 성공 사용 시각(last_used_at) 기준 1초가 지나야 다음 요청이 허용돼요.

초과 시 응답

HTTP 429 Too Many Requests

HTTP/1.1 429 Too Many Requests
Retry-After: 1
Content-Type: application/json; charset=utf-8

{
  "error": "Rate limit exceeded",
  "limit": "1 rps"
}

• Retry-After: 1 — 최소 1초 뒤에 다시 시도하라는 힌트예요.
• 본문의 limit 필드는 사람이 읽기 쉬운 한도 표기예요.

클라이언트 구현 팁

1. 고정 간격 폴링

상태 모니터라면 1.1~2초 이상 간격으로 호출하세요.

const INTERVAL_MS = 2000;

async function tick() {
  const res = await fetch("https://api.mineplatform.kr/v1/servers", {
    headers: { Authorization: `Bearer ${process.env.MP_API_KEY}` },
  });
  if (res.status === 429) {
    const wait = Number(res.headers.get("Retry-After") || "1") * 1000;
    await new Promise((r) => setTimeout(r, wait));
    return tick();
  }
  // ...
}

setInterval(() => void tick(), INTERVAL_MS);

2. 429 재시도 (백오프)

대기 = max(Retry-After, 1) 초
필요하면 지수 백오프 (1s → 2s → 4s, 상한 30s)

무한정 재시도하지 말고, 실패를 로그로 남기세요.

3. 여러 키로 우회하지 마세요

한도 우회를 위해 키를 여러 개 돌려 쓰는 행위는 약관·남용 정책에 걸릴 수 있어요.
높은 처리량이 필요하면 고객센터로 문의해 주세요.

헬스 체크와 한도

GET /health 는 API 키가 필요 없고, 키 RPS와도 분리되어 있어요.
업타임 로봇은 /health를 쓰고, 데이터 조회만 /v1/servers를 쓰세요.

자주 하는 실수

증상	원인	해결
가끔만 429	봇이 1초 미만 간격으로 호출	간격을 2초 이상으로
배포 직후 연속 401/429	헬스와 데이터 URL을 같은 키로 초당 여러 번	헬스만 분리
로컬에서 두 프로세스가 같은 키 사용	프로세스마다 독립 타이머	키를 나누거나 한 프로세스만 호출