AI 에이전트가 위키피디아 정보를 가져오다가 429 Too Many Requests 오류를 반환했다면, 자동 재시도를 잠시 중단하는 것이 먼저입니다. 실패한 요청의 URL, HTTP 상태 코드, 응답 본문, Retry-After 헤더부터 확보하세요. 429는 요청 제한 신호지만, 이 숫자 하나만으로 정확한 제한 원인이나 영구 차단 여부를 판단할 수는 없습니다.
위키피디아 정보를 조회하는 API도 종류에 따라 적용 기준이 다릅니다. MediaWiki Action API와 REST API에는 2026년 도입된 Wikimedia 전역 요청 제한이 적용되지만, Lift Wing이나 Wikidata Query Service에는 동일한 제한표를 그대로 사용할 수 없습니다. 따라서 어떤 API에서 오류가 발생했는지 구별한 뒤 대기시간과 요청 설정을 정해야 합니다.
또한 5초만 기다리거나 API 키를 새로 발급받는다고 모든 429 오류가 해결되지는 않습니다. 실제 요청 빈도와 동시 호출량, User-Agent, 인증 상태를 확인하고 필요한 설정을 수정하세요. 이후 대기 조건을 준수한 상태에서 단일 요청부터 다시 실행해 보세요. 정상 응답이 반복해서 유지되면 자동화를 단계적으로 재개하고, 오류가 계속된다면 추가 호출을 보류하는 편이 안전합니다.
429 오류가 뜨면 재시도보다 응답 확인이 먼저입니다
AI 에이전트가 위키피디아 검색을 수행하다 실패했다면, 먼저 에이전트가 호출한 도구의 실행 기록을 열어보세요. 화면에 보이는 'Wikipedia API 오류'라는 이름보다 실제 요청이 어디로 전송됐는지가 중요합니다.
실행 기록에서는 실패한 최종 요청 URL과 HTTP 상태 코드·응답 본문을 함께 확보합니다. 이어 응답 헤더의 Retry-After, 실제 전송된 User-Agent, 오류 발생 시각을 기록하세요. 인증 토큰과 세션 쿠키 등 비밀 정보는 외부에 공유하지 마세요.
대표적인 엔드포인트 식별 단서는 다음과 같습니다.
/w/api.php: MediaWiki Action API의 대표적인 진입점입니다./w/rest.php: MediaWiki REST API의 대표적인 경로입니다.api.wikimedia.org: Wikimedia의 별도 API 접근 경로이므로 실제 하위 엔드포인트까지 확인해야 합니다.- Lift Wing·Wikidata Query Service: 서비스별 요청 제한과 오류 처리 지침을 별도로 확인해야 합니다.
이 경로들은 식별에 도움이 되는 단서일 뿐, 모든 Wikimedia API 주소를 분류하는 완전한 규칙은 아닙니다. 중간에 프록시나 API 연동 도구를 사용하는 경우에는 그 도구에 설정된 주소뿐 아니라 실제 최종 요청 경로도 확인하는 것이 좋습니다.
응답 상태도 함께 살펴야 합니다. HTTP 429는 요청 제한에 대한 대응이 필요하지만, HTTP 503은 서버 과부하 등 다른 문제일 수 있습니다. Action API의 ratelimited는 편집 같은 개별 동작 제한과 관련되고, maxlag는 데이터베이스 지연과 관련됩니다. 특히 maxlag는 HTTP 200 응답 안에 오류 정보가 포함될 수 있으므로 상태 코드만으로 성공을 판단해서는 안 됩니다.
Wikimedia의 요청 제한은 API 게이트웨이뿐 아니라 다른 요청 처리 계층에서도 적용될 수 있습니다. 따라서 HTTP 429를 전역 API 제한 초과로 단정하지 마세요. 실제 서비스, 응답 헤더, 요청 기록을 함께 봐야 적절한 해결 경로를 선택할 수 있습니다.
지금 확인한 상황에 따라 다음 행동을 고르세요
| 확인한 상황 |
판단 |
다음 행동 |
| Action API·REST API에서 HTTP 429 발생 |
요청 제한 대응 필요 |
Retry-After, 호출량, 식별 상태 확인 |
| Retry-After 헤더가 있음 |
명시된 대기 조건 존재 |
지정된 시간까지 기다림 |
| Retry-After 헤더가 없음 |
별도 재시도 대기 정책 필요 |
해당 서비스의 공식 대기·백오프 권고 적용 |
| 실제 분당 요청량이나 동시 호출량이 높음 |
호출 구조 조정 필요 |
속도·동시성 축소 및 중복 요청 정리 |
| User-Agent나 인증 상태가 부적절함 |
요청 식별 문제 가능 |
실제 전송값과 인증 방식을 대조한 뒤 문제가 확인된 설정만 수정 |
| Lift Wing·Wikidata Query Service에서 429 발생 |
전역 제한표를 그대로 적용할 수 없음 |
해당 서비스의 제한 문서 확인 |
| 수정 후 정상 응답이 안정적으로 유지됨 |
단계적 복구 가능 |
호출량을 통제하면서 자동화 재개 |
| 수정 후에도 429가 반복됨 |
추가 진단 필요 |
자동 재호출 보류 |
AI ZIP(aizip.ai.kr)에서는 이 문제를 실제 API와 응답을 먼저 구별하고, 대기 조건과 호출 설정을 수정한 뒤 재실행 여부를 판단하는 순서로 정리합니다.
오류 유형을 구분했다면 다음은 재호출 시점입니다. Retry-After에 맞춰 다음 호출 시점을 정하세요. 헤더가 없다면 사용 중인 API에 적용되는 공식 대기·백오프 권고를 기준으로 판단합니다.
Retry-After가 있다면 얼마나 기다려야 할까요?
HTTP 429 응답에서 가장 먼저 살필 헤더는 Retry-After입니다. 이 헤더는 서버가 요청을 다시 시도하기 전에 어느 정도 기다려야 하는지 알려주는 정보입니다.
예를 들어 응답에 Retry-After: 60이 있다면 최소 60초 동안 해당 재시도를 보류해야 합니다. 값이 항상 초 단위 숫자로 전달되는 것은 아닙니다. HTTP 표준에서는 특정 날짜와 시각을 지정하는 형식도 허용하므로, 자동 재시도 로직은 두 형식을 모두 처리할 수 있어야 합니다.
Wikimedia의 전역 API 요청 제한 문서는 429 또는 503 응답에 Retry-After가 포함될 수 있다고 설명합니다. 헤더가 없다면 최소 5초 동안 기다리거나 지수 백오프를 적용하도록 권고합니다.
지수 백오프는 실패할 때마다 재시도 간격을 늘리는 방식입니다. 짧은 간격으로 같은 요청을 반복하는 것보다 서버 부하를 줄이는 데 적합합니다. 다만 이 방식에도 최대 재시도 횟수와 중단 조건이 있어야 합니다.
5초 대기는 해결 보장 시간이 아닙니다. '5초 후 다시 호출하면 무조건 정상 작동한다'거나 '5초 간격으로 계속 호출해도 된다'는 의미로 해석해서는 안 됩니다.
실제로는 Retry-After를 준수하면서 자동 재시도에 상한을 두고, 같은 오류가 반복되면 추가 호출을 멈추도록 구성하는 편이 낫습니다. Wikimedia가 모든 AI 에이전트에 공통으로 적용되는 최대 재시도 횟수를 지정한 것은 아니므로, 횟수 상한은 사용하는 시스템의 작업 특성에 맞게 별도로 정해야 합니다.
또 하나 주의할 점은 기다리는 동안 다른 워크플로가 계속 같은 API를 호출할 수 있다는 것입니다. 오류가 발생한 작업 하나만 멈췄더라도 동일한 요청 주체의 다른 작업에서 트래픽이 계속 발생한다면 제한 상황이 해소되지 않을 수 있습니다.
기다렸는데 또 429라면 요청량과 병렬 호출을 확인합니다
충분히 기다린 뒤에도 오류가 다시 나타난다면 에이전트의 실행 기록에서 실제 분당 요청 수와 최대 동시 요청 수를 계산해 보세요. 호출 시각을 기준으로 1분 동안 실제 전송된 요청 건수를 세고, 동시에 진행된 요청의 최대 개수도 별도로 기록합니다. 프롬프트를 한 번 실행했다고 외부 API도 한 번만 호출된다는 뜻은 아닙니다.
에이전트는 검색 결과를 다시 조회하거나 여러 항목의 상세 정보를 가져올 수 있습니다. 자동 재시도가 중첩돼 있다면 예상보다 많은 요청이 발생할 가능성도 있습니다. 다만 실제로 이런 동작이 있었는지는 로그를 통해 확인해야 합니다.
내 AI 에이전트의 분당 요청 제한은 얼마일까요?
2026년 10월 17일 기준 Wikimedia 공식 요청 제한표에는 다음과 같은 주요 구간이 제시되어 있습니다.
- IP 주소 외에 별도의 식별 정보가 없는 요청: 분당 10회
- 규정을 준수하는 User-Agent를 사용하는 비인증 봇: 분당 200회
- 신규 사용자 또는 편집 이력이 적은 인증 사용자: 분당 200회
- 활동 이력이 충분한 인증 편집자: 분당 2,000회
- 커뮤니티가 승인한 봇 계정 등 일부 대상: 해당 전역 요청 제한 면제
이 제한은 해당 전역 API 제한에 적용되는 구간입니다. 모든 AI 에이전트에 분당 200회가 허용된다거나, 계정에 로그인하면 자동으로 2,000회까지 호출할 수 있다는 뜻이 아닙니다.
Wikimedia 프로젝트 전반에 걸쳐 적용되는 제한이므로 여러 위키로 호출 대상을 나눈다고 각각 독립적인 허용량이 생기는 것도 아닙니다. 실제 요청이 어떤 식별·인증 범주로 분류되는지가 우선입니다. 운영 정책과 수치는 변경될 수 있으므로 설정을 확정하기 전에 Wikimedia 공식 API 요청 제한표에서 현재 기준을 대조하세요.
분당 요청 수만 줄이면 충분할까요?
그렇지 않습니다. Wikimedia는 모범 사례에서 동시 요청 수를 3개 이하로 제한하도록 안내합니다. Action API 사용 지침에서는 가능하다면 한 요청이 끝난 다음 다른 요청을 보내는 직렬 호출을 권장합니다.
분당 100회 요청하는 작업이라도 짧은 순간에 여러 요청을 동시에 실행하면 부담이 집중될 수 있습니다. 반대로 동시 요청이 1개뿐이어도 호출 간격이 지나치게 짧다면 분당 제한을 초과할 수 있습니다.
따라서 분당 요청 수와 동시 요청 수는 별도로 관리해야 합니다. 동시 요청을 3개 이하로 설정했다는 이유만으로 429가 더 이상 발생하지 않는다고 보장할 수는 없습니다.
요청 구조를 점검할 때는 하나의 에이전트 작업에서 외부 API가 몇 번 호출됐는지, 실패 후 HTTP 라이브러리와 에이전트가 각각 재시도하는지, 같은 문서를 반복 조회하는지 순서대로 살펴보세요.
동일한 데이터를 여러 번 가져오는 상황이라면 캐싱이 도움이 됩니다. Action API는 가능한 경우 여러 항목을 한 요청으로 조회하는 방법도 지원합니다. 다만 캐시 유효기간은 데이터가 얼마나 자주 바뀌는지에 맞춰 설정해야 합니다.
ETag 등을 이용하는 조건부 요청도 데이터 전송량을 줄이는 데 활용할 수 있지만, 서버에 새로운 요청을 보내는 행위 자체가 사라지는 것은 아닙니다. HTTP 304 응답을 받았다는 이유로 요청 횟수 제한에서 자동 제외된다고 가정해서는 안 됩니다.
호출량을 줄이기 위해 요청 시점을 분산하는 것과, 제한을 피하려고 IP나 User-Agent를 여러 개로 나눠 사용하는 행위도 구별해야 합니다. Wikimedia의 API 사용 정책은 과도한 요청을 숨기기 위한 식별 정보 분산을 금지합니다.
호출량을 줄여도 해결되지 않으면 User-Agent와 인증 상태를 확인합니다
요청 빈도와 동시성을 조절했는데도 429가 반복된다면 Wikimedia가 해당 요청을 어떤 클라이언트의 호출로 인식하는지 확인할 차례입니다.
우선 실제로 전송된 User-Agent와 인증 방식을 살펴보세요. User-Agent는 API를 호출하는 프로그램을 식별하는 HTTP 헤더입니다. Wikimedia는 자동화 클라이언트가 프로그램 이름과 운영자에게 연락할 수 있는 정보를 포함하도록 안내합니다.
형식의 예시는 다음과 같습니다.
User-Agent: ExampleBot/1.0 (https://example.org/bot/; bot@example.org)
위 문자열은 형식을 보여주기 위한 예시이므로 그대로 복사하지 말고 실제 프로그램 정보와 유효한 연락 수단으로 바꿔야 합니다. python-requests처럼 일반적인 라이브러리 이름만 사용하는 기본 User-Agent는 적절한 식별 정보로 인정받지 못하거나 차단 대상이 될 수 있습니다.
브라우저에서 실행하는 JavaScript는 User-Agent를 직접 변경하기 어려울 수 있습니다. 이 경우 Wikimedia가 안내하는 Api-User-Agent 헤더를 사용할 수 있습니다. 서버 측 에이전트라면 외부 요청을 만드는 HTTP 라이브러리에서 실제 전송 헤더를 확인해야 합니다.
User-Agent가 부적절하면 429뿐 아니라 403 등의 접근 문제도 발생할 수 있습니다. 따라서 이 설정을 바꾸는 것만으로 모든 429 오류가 해결된다고 볼 수는 없습니다.
API 키나 OAuth 인증을 추가하면 해결될까요?
인증은 요청 주체를 더 정확하게 식별하는 데 도움이 되지만, 인증 정보를 추가했다고 높은 요청 한도가 자동 적용되는 것은 아닙니다.
Wikimedia는 인증 방식과 현재 사용자 권한에 따라 제한 수준을 구분합니다. 특히 OAuth 1.0 접근 토큰은 토큰만 보내는 경우 전역 요청 제한 체계에서 비인증 요청으로 취급될 수 있습니다. 세션 쿠키가 함께 필요한지 확인해야 합니다.
OAuth 2.0 owner-only 방식 역시 과거 토큰에 기록된 높은 요청 제한값이 새 전역 제한 체계에서 그대로 유지되는 것은 아닙니다. 현재 권한과 실제 인증 세션이 중요하며, 일부 api.wikimedia.org 엔드포인트에는 별도의 예외가 있습니다.
반대로 여러 사용자를 대신하는 OAuth 2.0 애플리케이션의 Authorization token flow에서는 쿠키를 보내지 말라는 공식 예외가 있습니다. 모든 OAuth 요청에 쿠키를 추가하는 방식은 잘못된 설정이 될 수 있습니다.
따라서 이미 인증을 사용 중이라면 토큰을 새로 만들기 전에 실제 인증 방식과 세션 처리, 요청 호스트, 현재 계정 권한을 대조하세요. 자신의 인증 방식에 해당하는 쿠키 조건은 Wikimedia API 요청 제한 FAQ에서 확인할 수 있습니다.
커뮤니티가 승인한 봇 계정이나 일부 Wikimedia Cloud Services 서버 측 요청은 2026년 전역 요청 제한의 면제 대상이 될 수 있습니다. 그러나 프로그램 이름에 'bot'이 포함돼 있다는 사실만으로 승인된 봇이 되는 것은 아니며, 해당 면제가 다른 운영상 요청 제한까지 없애는 것도 아닙니다.
수정 후 한 번 성공했다면 자동화를 다시 켜도 될까요?
재시도 대기와 요청 설정을 수정한 뒤 정상 응답이 나왔다면 우선 첫 번째 복구 단계는 통과한 것입니다. 다만 API 요청 한 번이 성공했다는 사실만으로 에이전트 전체가 안정적으로 복구됐다고 판단하기는 어렵습니다.
먼저 전체 자동화를 실행하기보다 제어된 단일 호출부터 재검증하세요. 정상 HTTP 상태 코드뿐 아니라 기대한 데이터가 실제로 반환됐는지도 확인해야 합니다. Action API에서는 상태가 200이어도 오류 본문이 포함될 수 있기 때문입니다.
단일 요청이 성공했다면 호출 속도와 동시 실행을 제한한 상태에서 실제 작업을 소규모로 실행해 보세요. 이때는 분당 호출량, 재시도 발생 여부, 429 재발 여부를 함께 기록합니다.
마지막으로 원래 작업에 가까운 수준까지 단계적으로 늘려 봅니다. 이 과정에서도 적용되는 요청 제한을 준수하고, 429가 다시 발생하면 자동 대기·중단 기능이 실제로 작동하는지 살펴야 합니다.
이 순서는 안정적인 복구를 판단하기 위한 실무적인 검증 방법입니다. Wikimedia가 모든 API 클라이언트에 동일한 테스트 횟수나 합격 기준을 정해 둔 것은 아닙니다.
그래도 429가 반복된다면 어디까지 확인해야 할까요?
호출량을 줄였고 User-Agent와 인증 상태도 적절한데 오류가 반복된다면 자동 재호출을 보류하고 남아 있는 원인을 확인해야 합니다.
특히 같은 요청 주체가 다른 워크플로에서 API를 호출하고 있지는 않은지, 중간 프록시나 다른 요청 처리 계층에서 제한이 적용되는지, 실제 사용 중인 서비스가 별도의 운영 제한을 갖고 있는지 살펴보세요.
Wikidata Query Service처럼 별도의 요청 제한을 적용하는 서비스에서는 전역 요청 제한표의 숫자만 기준으로 재시도해서는 안 됩니다. 서비스별 감속 지침을 무시한 반복 호출은 추가 접근 제한으로 이어질 수 있습니다.
기본적인 모범 사례를 준수한 뒤에도 필요한 접근량을 확보하지 못하는 봇 운영자는 Wikimedia Foundation의 안내에 따라 bot-traffic@wikimedia.org로 문의할 수 있습니다. 문의 시에는 실제 API 엔드포인트, 오류 발생 시각, 응답 상태와 헤더, 요청 빈도, User-Agent, 사용한 인증 방식, 이미 수행한 조치를 정리하는 것이 도움이 됩니다. 단, 토큰이나 세션 쿠키 같은 비밀 인증 정보는 전달하지 마세요.
현재 상태가 재개 가능한지 판단할 때는 다음 기준으로 정리할 수 있습니다.
- 재개: 적용 제한을 준수하면서 정상 응답이 유지되고, 429 발생 시 대기·중단 처리가 정상 작동하는 경우
- 설정 추가 변경: 과도한 호출량, 중복 재시도, 부적절한 User-Agent 또는 인증 처리에서 해결되지 않은 문제가 확인된 경우
- 보류: 오류 원인을 충분히 확인할 수 없거나, 조치 후에도 429가 반복되는 경우
429 오류를 해결한다는 것은 요청 한 번을 성공시키는 것에 그치지 않습니다. 실제 에이전트가 요청 제한을 준수하면서 작업을 이어갈 수 있어야 합니다. 지금 오류가 지속되고 있다면 재시도 횟수를 더 늘리기보다 확인되지 않은 호출 경로와 설정을 먼저 좁히는 것이 다음 행동입니다.
English reference: If an AI agent receives HTTP 429 from a Wikimedia API, identify the endpoint, respect Retry-After, and review request frequency, concurrency, User-Agent, and authentication. Resume automation gradually only after controlled requests remain stable.
자주 묻는 질문
에이전트 도구에는 429 오류만 표시되고 Retry-After 헤더가 보이지 않습니다. 어떻게 해야 하나요?
도구의 상세 실행 기록이나 HTTP 요청 단계에서 원본 응답을 확인해 보세요. 사용 중인 연동 도구가 헤더를 표시하지 않는다면 해당 도구의 로그 설정과 응답 전달 방식을 확인해야 합니다. 헤더가 실제로 없는 것인지, 화면에만 표시되지 않는 것인지를 구별하지 못한다면 대기시간을 임의로 확정하지 마세요. 확인된 서비스별 공식 권고에 맞춰 재시도를 제한하고, 필요한 경우 자동 실행을 보류한 상태에서 응답 정보를 추가로 확보하는 편이 안전합니다.
참고자료
자료 확인일: 2026년 10월 17일. 공개된 공식자료와 서비스 안내를 기준으로 정리했습니다. 정책·가격·서비스 조건은 변경될 수 있으므로 실제 이용 전 최신 안내를 확인하세요.
댓글
댓글 쓰기