텔레그램 API 오류 읽기 — FLOOD_WAIT 와 다시 보내기

오류는 숫자와 이름 두 칸

텔레그램 API 의 오류는 숫자 코드(큰 분류)와 오류 이름(대문자·밑줄로 된 구체적인 이유, 예 PHONE_CODE_INVALID)으로 옵니다. 처리 방법은 이름으로 정하고, 모르는 이름이 오면 숫자 분류로 대처합니다. 이름 끝의 _X 자리에는 숫자(초·데이터 센터 번호 등)가 들어갑니다.

코드	뜻	대표 이름 · 할 일
303	다른 데이터 센터로 가라	PHONE_MIGRATE_X · USER_MIGRATE_X · FILE_MIGRATE_X · NETWORK_MIGRATE_X — X 번 데이터 센터로 옮겨 다시 요청(데이터 센터)
400	요청이 잘못됐다	입력값을 고쳐야 한다 — 사용자에게 알맞은 문장으로 알린다
401	로그인이 필요하다	AUTH_KEY_UNREGISTERED · SESSION_REVOKED · SESSION_EXPIRED — 세션이 끊겼으니 다시 로그인(로그인 흐름)
403	권한·공개 범위 때문에 안 된다	상대의 개인정보 설정, 관리자 권한 부족 등 — 다시 보내도 같다
404	없는 것을 불렀다	지워진 메시지·대화 등
406	사용자에게 따로 알릴 일	앱이 오류를 직접 띄우지 않는다 — 서버가 서비스 알림으로 보여 준다
420	너무 많이·빨리 요청했다	FLOOD_WAIT_X — X 초 기다린 뒤 다시
500	서버 쪽 문제	잠시 뒤 다시. 계속되면 요청 내용을 줄여 본다

표에 없는 숫자가 오면 서버 쪽 문제(500)처럼 다룹니다. 메서드마다 공식 문서에 가능한 오류 목록이 있지만, 그 목록이 전부라고 믿지 않고 모르는 이름에도 대비합니다.

FLOOD_WAIT — 기다리는 게 정답

• FLOOD_WAIT_X 는 'X 초 동안 이 요청을 하지 말라'는 뜻입니다. X 초를 그대로 기다린 뒤 다시 보냅니다. 기다리는 동안 같은 요청을 되풀이하면 기다릴 시간이 늘어나고, 반복되면 계정이 제한될 수 있습니다.
• FLOOD_PREMIUM_WAIT_X 는 일반 계정에만 걸리는 속도 제한입니다(예: 파일 받기 속도) — 텔레그램 프리미엄이면 풀립니다.
• 근본 해결은 요청 수를 줄이는 것입니다. 같은 정보를 반복해서 묻지 말고 저장해 두고(페이지 나누기·hash), 여러 대화에 보내는 일은 간격을 둡니다.

처리 순서 한 줄 요약

1. 이름을 알면 이름대로(옮기기·다시 로그인·기다리기·입력 고치기).
2. 이름을 모르면 숫자 분류대로.
3. 숫자도 모르면 서버 문제로 보고 잠시 뒤 한 번만 다시.

봇 API(HTTP)의 오류는 모양이 조금 다릅니다(ok:false · error_code · description) — 봇 API 첫 요청.