UPS API OAuth2.0令牌交换返回无效授权码问题排查

问题场景 #

我使用测试账号已成功完成UPS API的OAuth 2.0对接，但客户使用自身账号调用令牌接口时，持续返回如下错误：

{"response":{"errors":[{"code":"10400","message":"Invalid authorization code"}]}}

请求详情：

POST /security/v1/oauth/token HTTP/1.1 
Authorization: Basic [b64 id:secret] 
Host: onlinetools.ups.com 
Content-Type: application/x-www-form-urlencoded 
Content-Length: 92
    
grant_type=authorization_code&code=[code]&redirect_uri=[callback]

已完成的验证：

• 客户端ID、密钥、授权码格式均无误
• 回调URI与客户UPS账号后台配置完全一致
• 授权码未过期且确认未被使用过
• 仅账号主体与测试账号不同，双方用客户账号测试均触发该错误

排查方向 #

• 核对环境一致性：确认客户账号与测试账号是否处于同一环境（沙箱/生产）。UPS的沙箱和生产环境的OAuth体系完全隔离，客户端凭证、授权码不能跨环境使用。如果测试用沙箱，客户账号是生产环境（或反之），必然会触发该错误。
• 验证授权码生成来源：确保客户的授权码是从对应环境的UPS授权页面获取的。生产环境授权地址为https://www.ups.com/lasso/oauth/authorize，沙箱环境为https://wwwcie.ups.com/lasso/oauth/authorize，混用环境生成的授权码无法通过验证。
• 检查Basic Auth编码：确认Authorization头中的Base64编码是严格按客户端ID:客户端密钥的格式拼接后生成，无额外空格、换行符，且编码结果未被URL转义。
• 确认授权码有效性：UPS授权码为一次性使用，即使首次换取令牌失败，该授权码也会失效。需要引导客户重新获取新的授权码后重试。
• 检查账号权限与客户端关联：确认客户的UPS账号已开通目标API的访问权限，且OAuth客户端已正确关联到该账号主体。账号权限不足或客户端关联错误也会导致授权码验证不通过。

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