Azure APIM触发rate-limit-by-key时返回非预期响应体问题

默认情况下，APIM的rate-limit-by-key策略触发限流后，会返回HTML格式的错误页面或简单文本提示，不符合规范的API响应要求。可以通过添加on-error策略自定义限流触发时的响应格式，具体配置如下：

完整策略示例 #

<policies>
    <inbound>
        <!-- 原有限流策略 -->
        <rate-limit-by-key calls="2"
                          renewal-period="60"
                          counter-key="@(context.Request.Headers.GetValueOrDefault("client-id",""))" />
    </inbound>
    <backend>
        <forward-request />
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <!-- 捕获限流触发的错误 -->
        <choose>
            <when condition="@(context.LastError.Reason == "RateLimitExceeded")">
                <return-response>
                    <!-- 设置标准限流状态码429 -->
                    <set-status code="429" reason="Too Many Requests" />
                    <!-- 指定响应格式为JSON -->
                    <set-header name="Content-Type" exists-action="override">
                        <value>application/json</value>
                    </set-header>
                    <!-- 构造自定义JSON响应体 -->
                    <set-body>@{
                        return Newtonsoft.Json.JsonConvert.SerializeObject(new {
                            statusCode = 429,
                            message = "请求次数超过限制，请稍后重试",
                            supportId = context.LastError.Source
                        });
                    }</set-body>
                </return-response>
            </when>
            <!-- 其他错误保持默认处理 -->
            <otherwise>
                <base />
            </otherwise>
        </choose>
    </on-error>
</policies>

关键说明 #

1. 错误捕获：通过context.LastError.Reason == "RateLimitExceeded"判断是否触发了限流，这是rate-limit-by-key策略触发时的固定错误标识。
2. 状态码规范：将状态码从默认的403改为HTTP标准的限流状态码429（Too Many Requests），更符合API设计规范。
3. 响应格式控制：通过set-header强制设置Content-Type为application/json，确保客户端识别响应格式。
4. 自定义响应体：使用C#代码构造包含状态码、提示消息和支持ID的JSON结构，满足业务对响应内容的需求。

配置完成后，触发限流时将返回如下格式的JSON响应：

{
    "statusCode": 429,
    "message": "请求次数超过限制，请稍后重试",
    "supportId": "11411346622183591440"
}

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