FedEx地址验证API返回不一致SYSTEM.UNKNOWN.ERROR响应问题

问题现象 #

• 完全相同的请求参数、每次请求使用新生成的 OAuth Token 时，请求随机返回正常地址校验结果，或返回错误码 SYSTEM.UNEXPECTED.ERROR
• 极低概率返回 SERVICE.UNAVAILABLE.EXCEPTION 错误，符合官方定义的服务临时不可用场景
• 无明确错误触发规律，请求格式符合官方 schema 要求，REST 通信链路本身无可靠性问题

根因定位 #

结合提供的代码，随机报错由以下几个问题共同导致：

1. 请求路径拼接错误
   初始化 RestClient 时已传入完整接口地址 https://apis-sandbox.fedex.com/address/v1/addresses/resolve，但初始化 RestRequest 时额外传入了 "/" 作为资源路径，最终实际请求 URL 会被拼接为 https://apis-sandbox.fedex.com/address/v1/addresses/resolve/，末尾多了一个斜杠。FedEx 沙箱环境是多节点部署，不同节点对末尾斜杠的路由规则处理不一致：部分节点做了兼容可以正常响应，部分节点无法匹配路由直接抛出系统内部错误，这是随机报错的核心原因。
2. 请求体传参不规范
   使用 request.AddParameter("", input, ParameterType.RequestBody) 传递 JSON 请求体时，不同版本的 RestSharp 会对请求体做额外的编码转义，甚至覆盖手动设置的 Content-Type 头，导致部分节点解析请求体失败返回系统错误。
3. 请求缺少必填字段
   当前代码序列化生成的请求 JSON 仅包含 addressesToValidate 字段，官方 schema 要求的顶层必填字段 inEffectAsOfTimestamp、validateAddressControlParameters 被注释。沙箱节点的参数校验逻辑不统一，部分节点宽松放过缺失字段的请求，部分节点严格校验直接返回错误。
4. Token 使用逻辑不合理
   每次请求都生成新的 OAuth Token 会触发沙箱环境的流控规则，且多节点部署下新生成的 Token 存在同步延迟，会偶发出现鉴权失败。
5. 缺少临时错误重试逻辑
   SYSTEM.UNEXPECTED.ERROR、SERVICE.UNAVAILABLE.EXCEPTION 都属于服务端临时错误，本身就需要通过重试规避，当前代码无任何重试和状态码判断逻辑。

修复方案 #

• 修正 URL 拼接逻辑：RestClient 初始化时传入根域名 https://apis-sandbox.fedex.com，RestRequest 初始化时传入接口路径 /address/v1/addresses/resolve；或者 RestClient 传入完整接口地址后，RestRequest 不传入路径参数，避免出现末尾多余斜杠。
• 规范请求体传参：使用 RestSharp 自带的 AddJsonBody() 方法直接传入请求对象，不需要手动序列化 JSON 字符串，也不需要手动设置 Content-Type 头，由组件自动处理编码和格式。
• 补全所有必填请求字段：构造请求对象时补充 inEffectAsOfTimestamp（传当前 UTC 时间的 ISO 格式字符串即可）、validateAddressControlParameters 两个顶层必填字段。
• 缓存 OAuth Token：FedEx OAuth Token 默认有效期 3600 秒，缓存 Token 直到过期前 5 分钟再刷新，不要每次请求都生成新 Token。
• 增加指数退避重试逻辑：针对 5xx 状态码、SYSTEM.UNEXPECTED.ERROR、SERVICE.UNAVAILABLE.EXCEPTION 三类临时错误，最多重试 3 次，每次重试间隔按 1s、2s、4s 递增。

修复后核心代码示例 #

// 全局复用RestClient，不要每次请求都新建
private static readonly RestClient _fedexClient = new RestClient("https://apis-sandbox.fedex.com");
// 缓存Token及过期时间
private static string _cachedToken;
private static DateTimeOffset _tokenExpireAt;

string ValidateAddressAPI(AddressInput requestBody)
{
    // Token过期前5分钟自动刷新
    if (string.IsNullOrEmpty(_cachedToken) || DateTimeOffset.UtcNow >= _tokenExpireAt.AddMinutes(-5))
    {
        var tokenRes = GenerateOauthTokenAPI(client_id, client_secret);
        _cachedToken = tokenRes.access_token;
        _tokenExpireAt = DateTimeOffset.UtcNow.AddSeconds(tokenRes.expires_in);
    }

    var request = new RestRequest("/address/v1/addresses/resolve", Method.Post);
    request.AddHeader("authorization", $"Bearer {_cachedToken}");
    request.AddHeader("x-locale", "en_US");
    request.AddJsonBody(requestBody);

    int retryCount = 0;
    while (retryCount < 3)
    {
        var response = _fedexClient.Execute(request);
        if (response.IsSuccessful)
        {
            var res = JsonConvert.DeserializeObject<AddressValidationRes>(response.Content);
            return res.output.addressResolutionResults[0].classification;
        }
        var errorRes = JsonConvert.DeserializeObject<FedexErrorRes>(response.Content);
        // 仅临时错误触发重试
        if (errorRes.errors.Any(e => e.code is "SYSTEM.UNEXPECTED.ERROR" or "SERVICE.UNAVAILABLE.EXCEPTION"))
        {
            retryCount++;
            Thread.Sleep((int)Math.Pow(2, retryCount) * 1000);
            continue;
        }
        // 非临时错误直接抛出
        throw new Exception($"地址校验失败：{string.Join(";", errorRes.errors.Select(e => e.message))}");
    }
    throw new Exception("地址校验接口重试3次仍失败");
}

// 构造请求时补全必填字段
var addressInput = new AddressInput()
{
    inEffectAsOfTimestamp = DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mm:ssZ"),
    validateAddressControlParameters = new ValidateControlParams()
    {
        includeResolutionTokens = true
    },
    addressesToValidate = new [] { new Addressestovalidate() { address = address1 } }
};

var result = ValidateAddressAPI(addressInput);

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