도구·errors

Discord API 에러코드 사전 - HTTP·JSON 에러 검색 | 디코모아

Discord API 에러코드를 빠르게 검색하고 해결법을 확인하세요. HTTP 상태 코드와 JSON 에러코드 전체 목록을 정리한 디스코드 봇 개발자 필수 사전.

🔍 API 에러코드 사전

Discord API의 HTTP 상태 코드, JSON 에러 코드, Gateway 에러를 검색하고 해결법을 확인하세요. 총 71개 수록.

OK요청 성공

💡 해결: 정상 동작입니다.

Created리소스 생성 성공

💡 해결: 정상적으로 생성되었습니다.

No Content성공했지만 응답 본문 없음

💡 해결: 정상 동작입니다. DELETE 등에서 자주 발생합니다.

Not Modified리소스가 변경되지 않음

💡 해결: 캐시된 데이터가 최신입니다.

Bad Request잘못된 요청 형식

💡 해결: 요청 본문이나 파라미터를 확인하세요. JSON 형식이 올바른지, 필수 필드가 누락되지 않았는지 검토합니다.

Unauthorized인증 실패

💡 해결: 봇 토큰이 유효한지 확인하세요. "Bot " 또는 "Bearer " 접두사가 올바른지 확인합니다.

Forbidden권한 부족

💡 해결: 봇에 필요한 권한이 있는지 확인하세요. 역할 계층에서 봇 역할이 대상보다 높은지 확인합니다.

Not Found리소스를 찾을 수 없음

💡 해결: ID가 올바른지, 리소스가 삭제되지 않았는지 확인하세요. API 엔드포인트 URL을 다시 검토합니다.

Method Not Allowed사용할 수 없는 HTTP 메서드

💡 해결: GET/POST/PUT/PATCH/DELETE 중 올바른 메서드를 사용하고 있는지 확인하세요.

Too many RequestsRate Limit 초과

💡 해결: 응답의 Retry-After 헤더 값만큼 대기 후 재시도하세요. X-RateLimit-* 헤더를 모니터링하세요.

Gateway UnavailableDiscord API 서버 문제

💡 해결: 디스코드 서버 문제입니다. 잠시 후 재시도하세요. status.discord.com을 확인하세요.

Server ErrorDiscord 서버 내부 오류

💡 해결: 디스코드 측 문제입니다. 지수 백오프(exponential backoff)로 재시도하세요.

General Error일반 오류 (불특정)

💡 해결: 요청 전체를 검토하세요. 대부분 잘못된 JSON 형식이 원인입니다.

Unknown Account알 수 없는 계정

💡 해결: 사용자 ID가 올바른지 확인하세요.

Unknown Channel알 수 없는 채널

💡 해결: 채널 ID가 올바른지, 채널이 삭제되지 않았는지 확인하세요.

Unknown Guild알 수 없는 서버

💡 해결: 서버 ID가 올바른지, 봇이 해당 서버에 있는지 확인하세요.

Unknown Member알 수 없는 멤버

💡 해결: 해당 사용자가 서버에 있는지 확인하세요.

Unknown Message알 수 없는 메시지

💡 해결: 메시지 ID가 올바른지, 메시지가 삭제되지 않았는지 확인하세요.

Unknown Role알 수 없는 역할

💡 해결: 역할 ID가 올바른지, 역할이 삭제되지 않았는지 확인하세요.

Unknown Emoji알 수 없는 이모지

💡 해결: 이모지 ID가 올바른지, 이모지가 삭제되지 않았는지 확인하세요.

Unknown Webhook알 수 없는 웹훅

💡 해결: 웹훅 ID가 올바른지, 웹훅이 삭제되지 않았는지 확인하세요.

Bots cannot use this봇이 사용할 수 없는 엔드포인트

💡 해결: 이 API는 사용자 계정 전용입니다. 봇에서는 사용할 수 없습니다.

Not allowed for bot users봇 사용자에게 허용되지 않음

💡 해결: 사용자 전용 기능입니다.

Slowmode rate limit슬로우모드 제한 초과

💡 해결: 채널의 슬로우모드 시간이 지난 후 다시 시도하세요.

Max Guilds최대 서버 수 도달 (100개)

💡 해결: 봇이 참여할 수 있는 서버 수 제한입니다. 불필요한 서버에서 봇을 제거하세요.

Max Friends최대 친구 수 도달

💡 해결: 봇은 친구 추가가 불가합니다.

Max Pins채널 핀 최대 수 도달 (50개)

💡 해결: 기존 핀 메시지를 해제하고 다시 시도하세요.

Max Roles서버 역할 최대 수 도달 (250개)

💡 해결: 불필요한 역할을 삭제하세요.

Max Webhooks채널 웹훅 최대 수 도달 (15개)

💡 해결: 불필요한 웹훅을 삭제하세요.

Max Emojis서버 이모지 최대 수 도달

💡 해결: 불필요한 이모지를 삭제하거나 서버를 부스트하세요.

Max Reactions메시지 리액션 최대 수 도달 (20종)

💡 해결: 리액션 종류를 줄이세요.

Max Channels서버 채널 최대 수 도달 (500개)

💡 해결: 불필요한 채널을 삭제하세요.

Max Invites서버 초대 최대 수 도달

💡 해결: 기존 초대를 삭제하세요.

Max Bans차단 목록에서 가져오기 실패

💡 해결: GUILD_BANS 인텐트 또는 BAN_MEMBERS 권한을 확인하세요.

Max Stickers서버 스티커 최대 수 도달

💡 해결: 불필요한 스티커를 삭제하거나 서버를 부스트하세요.

Unauthorized인증 정보 없음 또는 유효하지 않음

💡 해결: Authorization 헤더에 올바른 토큰이 있는지 확인하세요.

Need Verification계정 인증 필요

💡 해결: 봇 소유자 계정의 이메일/전화 인증이 필요합니다.

Request Entity Too Large요청 크기 초과

💡 해결: 파일 크기가 업로드 제한을 초과했습니다. 파일을 압축하거나 분할하세요.

Feature disabled서버에서 기능이 비활성화됨

💡 해결: 해당 기능이 서버에서 활성화되어 있는지 확인하세요.

User banned차단된 사용자

💡 해결: 해당 사용자가 서버에서 차단되어 있습니다. 차단을 해제하세요.

Already has that reaction이미 해당 리액션 추가됨

💡 해결: 이미 추가된 리액션입니다.

Missing Access접근 권한 없음

💡 해결: 봇이 해당 채널/서버에 접근 권한이 있는지 확인하세요. VIEW_CHANNEL 권한을 확인합니다.

Cannot send empty message빈 메시지 전송 불가

💡 해결: content, embeds, files 중 하나 이상을 포함해야 합니다.

Cannot send to user사용자에게 DM 전송 불가

💡 해결: 대상 사용자가 DM을 차단했거나, 봇과 공유 서버가 없습니다.

Cannot send in voice channel음성 채널에 메시지 전송 불가

💡 해결: 텍스트 채널에 메시지를 보내세요.

Missing Permissions권한 부족

💡 해결: 봇에 해당 작업에 필요한 권한을 부여하세요. 채널별 권한 재정의도 확인합니다.

Invalid Token유효하지 않은 토큰

💡 해결: 봇 토큰을 재생성하세요. Developer Portal > Bot > Reset Token

Cannot delete system message시스템 메시지 삭제 불가

💡 해결: 시스템이 생성한 메시지(입장/부스트 등)는 삭제할 수 없습니다.

Invalid file유효하지 않은 파일

💡 해결: 파일 형식이 올바른지, 파일이 손상되지 않았는지 확인하세요.

Bulk delete range벌크 삭제 범위 초과

💡 해결: 벌크 삭제는 2~100개 메시지, 14일 이내 메시지만 가능합니다.

Invalid Form Body유효하지 않은 요청 본문

💡 해결: 요청 JSON의 각 필드 타입과 값이 올바른지 확인하세요. 에러 메시지의 세부사항을 참고합니다.

Invalid hypesquad유효하지 않은 HypeSquad 하우스

💡 해결: 올바른 HypeSquad 하우스 값을 사용하세요.

Invalid guild유효하지 않은 서버

💡 해결: 서버가 존재하는지, 봇이 해당 서버에 있는지 확인하세요.

Cannot delete community channel커뮤니티 필수 채널 삭제 불가

💡 해결: 커뮤니티 서버의 규칙/업데이트 채널은 커뮤니티 설정을 먼저 변경해야 합니다.

Unknown Interaction알 수 없는 인터랙션

💡 해결: 인터랙션이 만료되었습니다 (3초 이내 응답 필요). deferReply()를 사용하세요.

Interaction already acked이미 응답된 인터랙션

💡 해결: 인터랙션에 이미 reply/deferReply 했습니다. followUp()을 사용하세요.

Interaction already responded인터랙션이 이미 응답함

💡 해결: editReply() 또는 followUp()을 사용하세요.

Unknown ErrorGateway 알 수 없는 오류

💡 해결: 재연결을 시도하세요.

Unknown Opcode알 수 없는 Opcode

💡 해결: Gateway로 보내는 payload의 op 코드를 확인하세요.

Decode Error페이로드 디코딩 실패

💡 해결: 보내는 JSON이 유효한지 확인하세요.

Not Authenticated인증되지 않은 세션

💡 해결: Identify 페이로드를 먼저 보내세요.

Authentication Failed인증 실패

💡 해결: 봇 토큰이 올바른지 확인하세요.

Already Authenticated이미 인증된 세션

💡 해결: Identify를 중복 전송하지 마세요.

Invalid Seq유효하지 않은 시퀀스 번호

💡 해결: 새 세션을 시작하세요. Resume 시 시퀀스 번호가 유효하지 않습니다.

Rate LimitedGateway Rate Limit 초과

💡 해결: 페이로드 전송 속도를 줄이세요.

Session Timed Out세션 타임아웃

💡 해결: 재연결하고 Resume을 시도하세요.

Invalid Shard유효하지 않은 Shard

💡 해결: Shard 설정이 올바른지 확인하세요. /gateway/bot에서 권장 shard 수를 확인합니다.

Sharding RequiredSharding 필요

💡 해결: 봇이 너무 많은 서버에 있어 Sharding이 필수입니다.

Invalid API Version유효하지 않은 API 버전

💡 해결: 최신 Gateway API 버전을 사용하세요 (현재 v10).

Invalid Intent(s)유효하지 않은 Intent

💡 해결: 인텐트 값이 올바른지, Developer Portal에서 Privileged Intent가 활성화되어 있는지 확인하세요.

Disallowed Intent(s)허용되지 않은 Intent

💡 해결: Developer Portal > Bot에서 해당 Privileged Intent를 활성화하세요. 100+ 서버 봇은 인증이 필요합니다.

💡 디버깅 팁

429 Too Many Requests — Rate Limit 발생 시 Retry-After 헤더를 확인하고 해당 시간만큼 대기하세요.
50013 Missing Permissions — 봇 역할의 위치가 대상 역할보다 높은지, 채널 권한 재정의가 없는지 확인하세요.
4014 Disallowed Intent — Discord Developer Portal에서 Privileged Gateway Intents를 활성화하세요.
에러 응답의 message와 errors 필드에 자세한 원인이 포함되어 있으니 반드시 확인하세요.
봇 라이브러리(discord.js, discord.py)의 에러 핸들러를 적극 활용하세요.

📚 참고 자료

Discord API 공식 문서•Discord 서비스 상태•Rate Limits 문서