디스코드 봇을 출시해 본 사람이라면 한 번쯤 겪어 봤을 거예요. 평범한 화요일인데 갑자기 어디서나 increased api errors가 뜨고 명령어의 절반이 실패하죠. 구글 트렌드는 2026년 중반에 이 문구를 "급상승" 검색어로 집계했어요. 사용자가 직접 검색할 만큼 자주 일어나는 일이에요. 이를 헤쳐 나가는 방법과, Noxyr 서버 API가 이 교훈에서 무엇을 가져왔는지 정리해 볼게요.
디스코드 API 실패의 세 가지 주요 유형
- 전역 장애 / 부분 장애: discordstatus.com에서 확인할 수 있어요. 증상: 어떤 요청이든 실패할 수 있고, 게이트웨이가 끊기고, 전반적으로 지연이 치솟아요.
- 429 Too Many Requests: 버킷의 제한을 초과한 거예요. 디스코드는 정확히 얼마나 기다려야 하는지 알려 주는
Retry-After헤더를 보내요. - 게이트웨이 잘못된 세션: WebSocket 세션이 오래되었다는 뜻이에요. 재개 토큰으로 다시 연결하고, 그것도 실패하면 새로 identify를 보내세요.
맑은 날이 아니라 실패를 기준으로 만드세요
- Retry-After를 지키세요. 자체 타이머로 재시도하지 마세요. 디스코드가 알려 준 정확한 시간만큼 기다린 다음 한 번만 재시도하세요. 429를 무시하고 밀어붙이는 봇은 차단당해요.
- 지터가 포함된 지수 백오프. 5xx 오류가 나면 1초, 2초, 4초, 8초를 기다리고, 여러 인스턴스가 한꺼번에 재시작해도 몰리지 않도록 작은 무작위 오프셋을 더하세요.
- 중요하지 않은 호출은 회로 차단하세요. 봇이 주간 요약을 게시하는데 디스코드 API가 저하되어 있다면, 쌓아 두지 말고 이번 실행은 건너뛰세요. 요약은 기다릴 수 있지만 장애는 기다려 주지 않아요.
- 실시간이 아닌 데이터는 모두 캐시하세요. 서버 이름, 채널 목록, 역할 ID는 로컬에 캐시해 두세요. 장애 중에도 캐시된 데이터로 계속 서비스할 수 있어요.
- 상태를 보여 주세요. 디스코드가 다운되어서 봇 명령어가 실패하고 있다면 사용자에게 알려 주세요. "현재 디스코드에 문제가 발생하고 있어요"라는 한 줄이 아무 말 없는 시간 초과보다 나아요.
Noxyr 서버 API는 이 교훈을 어떻게 적용하나요
Noxyr 서버 API는 디스코드 API가 아니라 자체 데이터베이스를 읽어요. 하지만 같은 원칙이 적용되고, 그 원칙이 설계를 형성했어요:
- 예측 가능한 오류: 모든 실패는 안정적인
error코드를 담은 JSON이에요. HTML도, 형식이 제각각인 응답도 없어요. - 속도 제한 헤더: 표준화된
RateLimit-*헤더를 제공해서, 클라이언트가 429에 걸리기 전에 물러설 수 있어요. - 우아한 성능 저하: 기반이 되는 디스코드 조회가 실패하면
/api/v1/server엔드포인트는 캐시된 서버 데이터로 대체해요. - 연쇄 실패 없음: 각 엔드포인트는 독립적으로 실패해요. 디스코드가 다운되어도 티켓 분석 엔드포인트는 디스코드가 아니라 Mongo에서 읽기 때문에 깨지지 않아요.
- 즉시 차단 스위치: 키나 범위를 비활성화하면 재시작 없이 바로 다음 요청부터 적용돼요.
디스코드가 꼬였을 때의 대응 절차
- 1. 먼저 discordstatus.com을 확인하세요. 나만 겪는 문제인가요?
- 2. 내 오류 로그를 보세요. 429, 5xx, 게이트웨이 연결 끊김이 있는지 확인하세요.
- 3. 디스코드 쪽 문제라면: 중요하지 않은 쓰기 작업을 멈추고, Retry-After를 지키고, 기다리세요.
- 4. 내 쪽 문제라면: 최근 배포, 캐시 무효화, 새 기능을 확인하세요.
- 5. 알리세요. 지원 채널에 짧고 솔직한 공지를 올리면 중복 신고 100건을 막을 수 있어요.
API 계층에 대해 더 보려면 Noxyr 서버 API, 디스코드 API vs Noxyr API, API 설계 원칙을 읽어 보세요.