Twitter API 429, 403, 401 오류: 원인과 해결 방법
X (Twitter) API의 429 Too Many Requests, 403 Forbidden, 401 Unauthorized 오류를 해결합니다. 공식 X API와 TwexAPI에서 각 코드의 의미, 확인할 헤더, 재시도해도 되는 경우를 정리했습니다.
요약: 429는 요청이 너무 많아서 기다려야 한다는 뜻이고, 403은 인증은 됐지만 권한이 없다는 뜻이며, 401은 인증 정보가 없거나 잘못됐다는 뜻입니다. 기다리면 해결되는 것은 429뿐입니다. 403과 401은 요청, 인증 정보, 접근 권한을 바꾸지 않으면 계속 같은 오류가 납니다.
| 코드 | 의미 | 먼저 확인할 것 | 재시도 |
|---|---|---|---|
| 429 Too Many Requests | 속도 제한, 사용량 한도 또는 계정의 일일 한도에 도달 | x-rate-limit-reset 또는 Retry-After 헤더 |
✅ 안내된 시간만큼 기다린 뒤 |
| 403 Forbidden | 인증은 됐지만 이 엔드포인트, 작업 또는 계정에 대한 권한이 없음 | 앱 접근 권한, 토큰 종류, 권한 범위, Credits, 대상 계정 | ❌ 권한부터 해결 |
| 401 Unauthorized | 인증 정보가 없거나, 잘못됐거나, 만료됐거나, 서명이 틀림 | Authorization 헤더와 사용 중인 키 또는 토큰 |
❌ 인증 정보부터 수정 |
API를 직접 호출하든 도구에서 오류를 보든 해결 방법은 같습니다. Request failed with status code 401이나 status code 429 같은 메시지는 HTTP 클라이언트(n8n과 많은 Node.js 봇이 쓰는 axios 등)가 출력하는 것으로, 그 안의 상태 코드는 호출한 API가 돌려준 값입니다.
먼저 어떤 API가 오류를 반환했는지 확인하세요
같은 코드라도 반환한 쪽에 따라 원인이 다릅니다.
- 공식 X API (
api.x.com또는api.twitter.com): 앱, 프로젝트, OAuth, 속도 제한 창에 관한 X 개발자 플랫폼 규칙을 따릅니다. - TwexAPI (
api.twexapi.io): TwexAPI API 키, Credits, 그리고 쓰기 작업에 전달한 X 세션과 관련된 오류입니다. 전체 목록은 TwexAPI 오류 코드 레퍼런스를 참고하세요. - x.com 웹사이트나 X 앱: 둘러보다가 나오는 “Rate limit exceeded”는 X가 계정에 건 제한이며, 개발자 API와는 관계가 없습니다.
Twitter API 429 Too Many Requests
공식 X API
X는 엔드포인트별로 보통 15분 또는 24시간 단위의 창으로, 앱별·사용자별 한도를 따로 적용합니다. 모든 응답에는 다음 세 헤더가 포함됩니다.
| 헤더 | 의미 |
|---|---|
x-rate-limit-limit |
현재 창에서 허용되는 요청 수 |
x-rate-limit-remaining |
현재 창에서 남은 요청 수 |
x-rate-limit-reset |
창이 초기화되는 Unix 타임스탬프 |
한도를 넘으면 X는 HTTP 429를 반환합니다. 예전 v1.1 형식 본문에는 오류 코드 88과 Rate limit exceeded가, 새로운 problem 형식에는 rate-limit-exceeded 타입이 들어 있습니다. 속도 제한이 아니라 사용량 한도에 도달한 경우에는 usage-capped가 반환됩니다.
해결 방법:
x-rate-limit-reset까지 기다리세요. 그 전에 재시도하면 다시429가 납니다.x-rate-limit-remaining을 지켜보세요. 0이 된 뒤가 아니라 그 전에 속도를 줄이세요.- 일일 한도를 확인하세요. 게시나 좋아요 같은 일부 쓰기 엔드포인트에는 앱별·사용자별 24시간 한도가 있어 몇 분 기다려서는 풀리지 않습니다.
- 캐시하고 요청을 분산하세요. 같은 프로필이나 트윗을 반복해서 가져오지 말고, 모든 작업을 정각에 한꺼번에 시작하지 마세요.
종량제 X API에서는 속도 제한과 요금이 별개입니다. 한도 안의 요청도 요금이 붙으므로, 캐시는 할당량과 비용을 모두 아껴 줍니다.
TwexAPI
TwexAPI의 429는 요청 스로틀링이거나, 쓰기 작업 중 X 계정 한도에 도달한 경우입니다(예: X 코드 344 게시 제한, 코드 502 일일 DM 한도). Retry-After 헤더나 retry_after 필드가 있으면 그 값을 따르세요. 계정의 일일 한도는 짧은 재시도로는 풀리지 않고 초기화 시점까지 기다려야 합니다. 백오프와 페이지네이션을 깨뜨리지 않는 복구 방법은 속도 제한을 참고하세요.
브라우저의 x.com 또는 X 앱
X는 계정마다 불러올 수 있는 양을 제한합니다. 스크롤하다가 “Rate limit exceeded”가 보이면 잠시 기다린 뒤 새로고침하고, 불필요한 탭과 자동 새로고침 확장 프로그램을 닫고, 여러 사람이 함께 쓰는 네트워크나 VPN 출구는 피하세요. 계정 없이 공개 프로필만 보고 싶다면 무료 트위터 뷰어를 쓸 수 있습니다.
Twitter API 403 Forbidden
403은 X나 TwexAPI가 인증 정보를 인식했지만 요청을 거부했다는 뜻입니다. 같은 요청을 반복하면 같은 403이 돌아옵니다.
공식 X API
| 원인 | 대표적인 증상 | 해결 방법 |
|---|---|---|
| 앱이 프로젝트에 등록되지 않았거나 접근 권한이 없음 | client-forbidden 타입. 예전 응답에서는 코드 453(“You currently have access to a subset of…”) |
Project에 연결된 앱의 키를 사용하고, 계정의 접근 범위에 해당 엔드포인트가 포함되는지 확인하세요 |
| 토큰 종류가 맞지 않음 | 앱 전용(app-only) Bearer Token으로 게시, 좋아요, 팔로우, DM을 시도 | 사용자 컨텍스트 토큰(OAuth 1.0a access token과 secret, 또는 OAuth 2.0 사용자 토큰)을 사용하세요 |
| 권한이나 scope 부족 | Read only 앱에서 발급한 사용자 토큰, 또는 tweet.write 같은 scope가 없는 OAuth 2.0 토큰 |
앱 권한을 Read and write(DM이 필요하면 Direct Messages 포함)로 바꾼 뒤 access token과 secret을 다시 생성하거나 사용자에게 다시 승인받으세요 |
| 보호되었거나 사용할 수 없는 리소스 | not-authorized-for-resource 타입 |
대상 계정이 비공개이거나 콘텐츠가 제한되어 있습니다. 사용자가 볼 수 있는 대상을 요청하세요 |
| 중복되거나 제한된 작업 | 같은 문구의 게시물, 답글이 제한된 트윗, 이미 좋아요한 트윗 | 내용을 바꾸거나 현재 상태를 확인한 뒤 재시도하세요 |
앱 권한을 바꿔도 이미 발급된 토큰은 갱신되지 않습니다. Read and write로 바꾼 뒤에는 반드시 사용자 토큰을 다시 생성하세요. 그렇지 않으면 게시는 계속 403을 반환합니다.
TwexAPI
TwexAPI의 403은 보통 다음 중 하나입니다.
- Credits 소진: Get Balance로 잔액을 확인하고 대시보드에서 충전하세요.
- 대상 계정이 비공개이거나 정지됨: 승인된 팔로워가 아니면 게시물을 읽을 수 없습니다. 공개 계정을 대상으로 요청하세요.
- 계정 또는 작업 제한: 쓰기에 사용하는 X 계정이 정지·잠금 상태이거나, 트윗이 답글을 제한하고 있거나(X 코드
433), X Premium이 필요한 작업입니다.
메시지별 해결 방법은 오류 코드 레퍼런스에 정리되어 있습니다.
Twitter API 401 Unauthorized
401은 요청이 본인 확인에 실패했다는 뜻입니다. 인증 정보를 고치지 않으면 몇 번을 재시도해도 성공하지 않습니다.
공식 X API
- 헤더 형식 오류: 앱 전용 요청은 정확히
Authorization: Bearer <token>형식이어야 합니다.Bearer누락, 불필요한 따옴표, 환경 변수 끝의 줄바꿈은 모두401을 일으킵니다. - 인증 정보 재생성 또는 폐기: 개발자 포털에서 키를 다시 생성하면 이전 키는 즉시 무효가 됩니다. 키를 저장한 모든 곳을 업데이트하세요.
- 인증 정보 조합 오류: OAuth 1.0a에는 consumer key와 secret에 더해 사용자의 access token과 secret이 필요합니다. 다른 앱의 키를 섞거나 토큰 자리에 API 키를 넣으면
401이 납니다. - OAuth 1.0a 서명 오류: 코드
32(Could not authenticate you)는 대개 서명이 잘못됐다는 뜻입니다. 파라미터의 URL 인코딩과 서버 시간이 정확한지 확인하세요. 타임스탬프가 어긋나면 서명이 무효가 됩니다. - OAuth 2.0 사용자 토큰 만료: 사용자 액세스 토큰은 만료됩니다.
offline.accessscope를 요청하고 리프레시 토큰으로 새 토큰을 받으세요.
TwexAPI
- API 키가 없거나 잘못됨: 대시보드에서 받은 키를
Authorization: Bearer YOUR_API_KEY로 보내세요. 자세한 내용은 인증을 참고하세요. - 쓰기 엔드포인트의 X 세션 만료: 게시, 좋아요, DM에서
Invalid auth_token이나 X 코드32가 나오면cookie로 전달한 X 세션 인증 정보가 만료된 것입니다. 그것만 갱신하면 되고 API 키는 문제가 없습니다.
성공할 수 있는 요청만 재시도하세요
아래 Python 헬퍼는 429와 일시적인 5xx만 재시도하고, 나머지 상태 코드는 바로 반환합니다. Retry-After(TwexAPI와 대부분의 HTTP API)와 x-rate-limit-reset(공식 X API)을 모두 지원합니다.
import random
import time
import requests
def request_with_retry(method, url, max_attempts=5, **kwargs):
for attempt in range(max_attempts):
response = requests.request(method, url, timeout=30, **kwargs)
if response.status_code != 429 and response.status_code < 500:
return response # success, or a 4xx that waiting won't fix
wait = None
retry_after = response.headers.get("Retry-After", "")
reset_at = response.headers.get("x-rate-limit-reset", "")
if retry_after.isdigit():
wait = int(retry_after)
elif reset_at.isdigit():
wait = max(0, int(reset_at) - time.time()) + 1
if wait is None:
wait = min(300, 5 * 2 ** attempt) + random.uniform(0, 1)
time.sleep(wait)
return response페이지를 넘기며 읽을 때는 429 이후 다음 페이지가 아니라 같은 커서로 재시도하세요. 쓰기 작업은 다시 보내기 전에 게시물, 좋아요, DM이 이미 반영됐는지 확인하세요. 타임아웃이 났다고 해서 작업이 실패했다는 뜻은 아닙니다.
공식 한도 자체가 문제라면
읽기에서 계속 429가 나거나 종량제 요금이 필요한 데이터보다 빨리 늘어난다면, 종량제 서드파티 API와 비용을 비교해 보세요. TwexAPI 읽기는 트윗 1,000개당 약 0.05달러이고 API 키만 있으면 되며 OAuth 설정이 필요 없습니다. 공식 X API는 게시물 읽기 1,000건당 5달러입니다. TwexAPI와 공식 X API 비교와 X API 요금 계산기를 참고하세요. TwexAPI는 X Corp.와 제휴하거나 보증받은 서비스가 아닙니다.
Twitter API 429, 403, 401 자주 묻는 질문
Twitter API 429는 얼마나 지속되나요?
x-rate-limit-reset이 가리키는 시각까지이며, 보통 15분 이내입니다. 게시처럼 24시간 한도가 있는 엔드포인트는 일일 창이 초기화될 때까지 막혀 있습니다. TwexAPI에서는 Retry-After 또는 retry_after를 따르세요.
X API로 트윗을 올리면 왜 403 Forbidden이 나오나요?
대개 토큰에 쓰기 권한이 없기 때문입니다. 앱 전용 Bearer Token을 쓰고 있거나, 앱이 Read only로 설정되어 있거나, Read and write로 바꾸기 전에 발급한 사용자 토큰을 쓰고 있는 경우입니다. 쓰기 권한을 켜고 사용자 토큰을 다시 생성한 뒤 사용자 컨텍스트 인증으로 게시하세요.
n8n의 “Request failed with status code 401”은 무슨 뜻인가요?
X API나 TwexAPI가 해당 HTTP 노드의 인증 정보를 거부했다는 뜻입니다. Authorization 헤더가 Bearer 뒤에 유효한 키나 토큰으로 되어 있는지, 인증 정보가 다시 생성되지 않았는지, 쓰기 작업에 사용자 컨텍스트 인증 정보를 쓰는지 확인하세요. TwexAPI 설정 예시는 n8n 가이드에 있습니다.
403과 429는 무엇이 다른가요?
429는 요청이 너무 많아 기다려야 한다는 뜻이고, 403은 애초에 그 요청이 허용되지 않는다는 뜻입니다. 429는 기다리면 풀리지만, 403은 접근 권한, 권한 범위, Credits 또는 대상을 바꿔야 합니다.
Twitter 오류 코드 88은 무엇인가요?
X 오류 코드 88은 Rate limit exceeded를 뜻하며 HTTP 429와 함께 반환됩니다. x-rate-limit-reset까지 기다린 뒤 다음 요청을 보내세요.
Twitter 오류 코드 32는 무엇인가요?
X 오류 코드 32는 Could not authenticate you를 뜻하며 HTTP 401과 함께 반환됩니다. 공식 API에서는 대개 OAuth 1.0a 서명이나 토큰이 잘못된 경우이고, TwexAPI 쓰기 엔드포인트에서는 전달한 X 세션 인증 정보가 만료됐다는 뜻입니다.
관련 페이지
- Twitter API 오류 코드 레퍼런스: TwexAPI의 모든 상태 코드와 X 오류 코드, 해결 방법
- 속도 제한: 백오프,
Retry-After, 페이지네이션을 깨뜨리지 않는 복구 - 오류 처리: MCP, SDK, 쓰기 작업 복구
- 인증: API 키와 X 세션 인증 정보