트위터(X) API 초과(429) 해결방법 총정리
2025년 9월 기준 · 최신 요금제/제한 흐름 반영 · 실무용 체크리스트/샘플코드/사례 포함
X(구 트위터) API를 쓰다 보면 가장 자주 만나는 에러가 429 Too Many Requests(레이트 리밋 초과)입니다.
본 가이드는 원인 → 진단 → 즉시대응(백오프·재시도) → 구조개선(큐·캐시·필드최적화·페이지네이션) → 장기대책(요금제/한도 상향) 순으로 한 번에 정리했습니다.
요금제·한도는 수시로 바뀝니다. 공식 개발자 포털 공지/문서를 먼저 확인해 최신 한도를 기준으로 설계하세요.
X 개발자 포털 공지/문서 확인
1) 먼저, 핵심 사실 요약
| 주제 | 핵심 포인트 | 비고 |
|---|---|---|
| 에러 의미 | 429는 “특정 창구(앱/토큰/엔드포인트/사용자)로 허용된 요청량을 초과”했다는 뜻 | HTTP 표준(Too Many Requests) |
| 헤더 | x-rate-limit-limit, x-rate-limit-remaining, x-rate-limit-reset 해석이 핵심 |
리셋 시각(Epoch)까지 대기/분산 |
| 요금제 | 2024~2025년 사이 Free / Basic / Pro / Enterprise 체계와 한도/가격이 상향/변경 | 정확 금액·한도는 시점별 공지 확인 |
| 근본 해결 | ① 백오프/재시도 ② 큐·스로틀링 ③ 캐시·필드절식 ④ 페이지네이션 전략 ⑤ 요금제 상향 | 서버·클라이언트 양측 적용 |
※ 엔드포인트별(예: followers, user tweets 등) 창당(15분) 호출량이 서로 다릅니다. 반드시 각 엔드포인트 한도를 따로 관리하세요.
2) (요약) 2024~2025 X API 요금제 변화 흐름
| 티어 | 개략 기능/용도 | 최근 변화 요지 | 설계 포인트 |
|---|---|---|---|
| Free | 기본 인증/간단 포스팅/제한적 읽기 | 읽기/쓰기 한도 매우 제한적 | 운영 서비스에는 부적합 |
| Basic | 소규모 앱/봇/프로토타입 | 2024 하반기 가격 인상 및 한도 조정 | 비용 대비 한도 면밀 검토 |
| Pro | 중규모 제품/상용 | 월 수천 달러 수준, 엔드포인트 확장 | 캐시/큐 전제의 안정화 필요 |
| Enterprise | 대규모/미션크리티컬 | 계약형 커스텀 한도/지원 | SLA·지원·법무·보안 동시 검토 |
가격과 정확 한도는 시점별 공지에 따라 바뀝니다. 운영팀은 주기적인 문서 재확인 및 알림 구독이 필요합니다.
최근 베이직/프로 한도·가격 변동이 공지된 바 있습니다. 현재 적용 중인 플랜을 재점검하세요.
요금제 변경 기사(TechCrunch) 보기
3) ‘왜 초과되나’ 빠른 진단 루틴
| 점검 항목 | 확인 방법 | 해결 가이드 |
|---|---|---|
| 헤더 파싱 | x-rate-limit-remaining/reset 수집/로그화 |
남은 호출 0이면 리셋 시각까지 큐 대기 |
| 엔드포인트별 창 | followers, tweets 등 리소스별 상이 | 창(15분)·버킷별로 쓰로틀 분리 |
| 페이지네이션 | 큰 계정 팔로워 전체 크롤링? | 토큰 기반 페이지를 배치·야간에 분할 |
| 필드 과다 | 확장/expansions, tweet.fields 남용 | 정말 쓰는 필드만 요청(Partial Response) |
| 중복 요청 | 캐시 미사용·폴링 과도 | ETag/캐시·Webhook/스트림 고려 |
4) 즉시 대응: 백오프·재시도·쓰로틀 모듈
// 의사코드: 429/한도 임박 시 지수 백오프 + 리셋까지 대기
async function callX(fetcher){
const res = await fetcher();
if (res.status === 429) {
const reset = +res.headers.get('x-rate-limit-reset') || 0; // epoch sec
const now = Math.floor(Date.now()/1000);
const waitMs = Math.max((reset - now) * 1000, 5_000);
await sleep(waitMs); // 리셋까지 대기
return fetcher(); // 1회 재시도
}
const remaining = +res.headers.get('x-rate-limit-remaining');
if (remaining <= 1) {
const reset = +res.headers.get('x-rate-limit-reset');
const delay = Math.max((reset - Math.floor(Date.now()/1000))*1000, 0);
await sleep(delay);
}
return res;
}
필수 구현 포인트
- 엔드포인트별 버킷 키(예:
GET /users/:id/followers)로 별도 쓰로틀러 관리 - 429·503 공통 재시도 로직(지수 백오프 + 재시도 최대횟수 + Jitter)
- 서버·워커에서 큐(예: Redis, SQS, Kafka)로 요청 분산
- 캐시(키: 요청 파라미터)로 동일 질의 중복 제거(짧은 TTL만으로도 효과 큼)
5) 구조 개선: 초과 자체를 줄이는 6가지
| 기법 | 설명 | 팁 |
|---|---|---|
| 필드 절식 | tweet.fields, user.fields 최소화 |
응답 축소 = 한도 소모 효율↑ |
| 페이지네이션 계획 | 대용량 계정은 야간/배치 수집 | 창당 요청량 균등 분할 |
| 캐시/ETag | 변동 적은 리소스 캐싱 | TTL + 조건부 요청(If-None-Match) |
| 웹훅/스트림 | 가능 시 폴링 대신 스트리밍 | 폴링 주기↓ = 호출량↓ |
| 사용자 vs 앱 한도 분리 | 권한 유형에 따라 버킷 분리 | 토큰 개념 혼동 금지(우회 금지) |
| 관측·알람 | 헤더·429 비율 모니터링 | 임계치 초과 전 사전 감속 |
여러 앱/토큰을 인위적으로 늘려 한도를 ‘우회’하는 행위는 약관 위반 위험이 있습니다. 정석은 설계 최적화 + 정식 한도 상향입니다.
엔드포인트별 한도·헤더 처리 예시는 SDK 문서가 가장 빠릅니다. 오픈소스 예제에서 레이트리밋 플러그인을 참고하세요.
twitter-api-v2 레이트리밋 문서 보기
6) 실전 사례 2가지
사례 A — followers 수집 429
문제: 15분 창에 15회 제한 엔드포인트를 수백 페이지로 연속 호출 → 429
해법: (1) 페이지 토큰 묶음을 큐에 분산 (2) 창당 호출 수 상한 설정 (3) 캐시로 중복 방지 (4) 리셋 시각까지 자동 대기
결과: 429 소멸, 전체 수집 시간은 늘었지만 운영 안정성↑
문제: 15분 창에 15회 제한 엔드포인트를 수백 페이지로 연속 호출 → 429
해법: (1) 페이지 토큰 묶음을 큐에 분산 (2) 창당 호출 수 상한 설정 (3) 캐시로 중복 방지 (4) 리셋 시각까지 자동 대기
결과: 429 소멸, 전체 수집 시간은 늘었지만 운영 안정성↑
사례 B — 게시/읽기 혼합 앱
문제: Free/Basic 티어에서 읽기 한도 급락 → 피드 로딩 실패 간헐 발생
해법: (1) 읽기 캐시 (2) 화면 단편 로딩(스켈레톤/프리페치) (3) 운영 시간대 분산 (4) 상위 티어 검토
결과: 사용자 오류율↓, 베이직→프로 업그레이드로 이벤트 피크 처리 안정화
문제: Free/Basic 티어에서 읽기 한도 급락 → 피드 로딩 실패 간헐 발생
해법: (1) 읽기 캐시 (2) 화면 단편 로딩(스켈레톤/프리페치) (3) 운영 시간대 분산 (4) 상위 티어 검토
결과: 사용자 오류율↓, 베이직→프로 업그레이드로 이벤트 피크 처리 안정화
7) 요금제 상향이 필요한 순간(체크리스트)
| 증상 | 주요 지표 | 권장 조치 |
|---|---|---|
| 피크 타임 429 빈번 | 15분 창당 80%↑ 사용 | 캐시/큐 후에도 지속 시 상위 티어 |
| 신규 기능/엔드포인트 추가 | 호출량 30%↑ 예상 | 사전 플랜 업그레이드 검토 |
| SLA 중요 고객 | 에러율 0.1% 이하 요구 | Pro/Enterprise + 모니터링 강화 |
8) 자주 묻는 질문(FAQ)
Q1. 429가 나면 바로 무엇을 해야 하나요?
x-rate-limit-reset까지 대기(백오프) 후 재시도하세요. 남은 호출이 0이면 추가 요청은 모두 429입니다.
Q2. 한도는 어디서 확인하나요?
응답 헤더(x-rate-limit-limit/remaining/reset)가 단기 기준, 공식 문서/요금제 페이지가 장기 기준입니다.
Q3. 페이지네이션 대량 수집은 어떻게 하나요?
토큰 별 큐잉 + 창당 상한 + 야간 배치 + 캐시로 나누어 처리합니다.
Q4. 가격이 자주 바뀌는데 대처법은?
변경 공지를 구독하고, 월간 비용·호출량 대시보드를 만들어 티어를 선제적으로 조정하세요.
9) 마무리 의견 & 운영 팁
레이트리밋은 피할 수 없는 플랫폼 특성입니다. 경험상 헤더 기반 쓰로틀러 + 큐 + 캐시만 안정적으로 적용해도 429의 80%는 사라집니다. 남은 20%는 피크 트래픽/새 기능/요금제 변화에서 나오니, 관측(Observability)과 의사결정 루틴(상향 기준)을 미리 정해두면 비용과 장애를 모두 줄일 수 있습니다.
가격·한도 변동 이슈를 한 번에 파악하고 싶다면 주요 IT 매체의 요약도 참고하세요. 공지 확인 후 내부 대책 회의를 추천합니다.
요금제 인상 요약(TechRadar) 보기
0 댓글