使用Discord OAuth2加入服务器时oauth2/token接口报400错误

问题场景 #

开发基于Discord OAuth2实现用户自动加入对应服务器（公会）功能时，编写Python代码如下：

import requests


API_ENDPOINT = 'https://discord.com/api/v8'
CLIENT_ID = 'client id here'
CLIENT_SECRET = 'client secret here'
REDIRECT_URI = "https://google.com"


def exchange_code(code):
    data = {
        'client_id': CLIENT_ID,
        'client_secret': CLIENT_SECRET,
        'grant_type': 'authorization_code',
        'code': code,
        'redirect_uri': REDIRECT_URI
    }
    headers = {
        'Content-Type': 'application/x-www-form-urlencoded'
    }
    r = requests.post('%s/oauth2/token' % API_ENDPOINT, data=data, headers=headers)
    r.raise_for_status()
    return r.json()


def add_to_guild(access_token, userID, guildID):
    url = f"{API_ENDPOINT}/guilds/{guildID}/members/{userID}"
    botToken = "bot token here"
    data = {
        "access_token": access_token,
    }
    headers = {
        "Authorization": f"Bot {botToken}",
        'Content-Type': 'application/json'
    }
    response = requests.put(url=url, headers=headers, json=data)
    print(response.text)


code = exchange_code('code here')['access_token']
add_to_guild(code, 'user id here', 'guild id here')

异常表现：

• 移除add_to_guild函数及下方调用代码时，程序运行无报错
• 加入add_to_guild相关逻辑后，始终抛出如下400错误，多次调整代码仍未解决：

Traceback (most recent call last):
  File "main.py", line 55, in <module>
    code = exchange_code('JZe2wsCPNxZwH6K7UJq130xmAu22xW')['access_token']
  File "main.py", line 22, in exchange_code
    r.raise_for_status()
  File "/home/runner/RelevantLooseRecovery/venv/lib/python3.8/site-packages/requests/models.py", line 1022, in raise_for_status
    raise HTTPError(http_error_msg, response=self)
requests.exceptions.HTTPError: 400 Client Error: Bad Request for url: https://discord.com/api/v8/oauth2/token

根因与修复方案 #

• 核心认知纠正：该错误和add_to_guild逻辑无代码层面关联。Python代码按顺序执行，报错触发点在exchange_code函数内部，此时程序根本没有运行到add_to_guild的逻辑。你观察到的「删函数就正常、加函数就报错」是时间差导致的错觉。
• 授权码规则不匹配：Discord返回的OAuth授权码（code参数）有效期仅10分钟，且只能使用一次。你调试不带加公会逻辑的版本时，已经消耗了当时的有效code；后续加上加公会逻辑再次运行，传入的是已经被使用/过期的code，请求token接口必然返回400。每次测试必须重新走完整OAuth授权流程，获取全新未使用的code再调用接口。
• Redirect URI不匹配：代码中配置的REDIRECT_URI必须和Discord开发者后台OAuth2板块配置的回调地址完全一致，包括协议（http/https）、域名、路径、末尾斜杠，任意字符不匹配都会触发400错误。
• 缺少必要授权Scope：要实现拉用户进服务器的功能，拼接OAuth授权链接时必须申请guilds.join和identify权限，否则后续就算拿到access_token，调用加公会接口也会返回403无权限。
• Bot权限校验：用于加人的Bot账号必须提前加入目标服务器，且拥有「创建即时邀请」「管理成员」权限，否则加人接口会调用失败。

调试时可以先在exchange_code函数的r.raise_for_status()前加一行print(r.json())，直接打印接口返回的错误码字段，比如返回invalid_grant就可以直接定位为code过期/已使用/回调地址不匹配问题，比直接抛出通用HTTP错误定位效率高很多。

内容的提问来源于stack exchange，提问作者forge