431 请求标头字段过大 - TooBigHeaders

您正在查看的是 Apigee Edge 文档。
转到 Apigee X 文档。 信息

问题

客户端应用收到 HTTP 状态代码 431 Request Header Fields Too Large（错误代码为 protocol.http.TooBigHeaders ）作为 API 调用的响应。

错误消息

客户端应用会获得以下响应代码： 

HTTP/1.1 431 Request Header Fields Too Large

此外，您可能还会看到以下错误消息： 

{
   "fault":{
      "faultstring":"request headers size exceeding 25,600",
      "detail":{
         "errorcode":"protocol.http.TooBigHeaders"
      }
   }
}

可能的原因

如果客户端应用作为 HTTP 请求的一部分发送到 Apigee Edge 的所有请求标头的总大小大于 Apigee Edge 中允许的限制（根据 RFC 6585 第 5 节：431 请求标头字段过大），就会发生此错误。

以下是导致此错误的可能原因：

原因 说明 适用的问题排查说明
请求标头大小超出允许的上限 客户端应用作为 HTTP 请求的一部分发送到 Apigee Edge 的所有标头的总大小超过 Apigee Edge 中允许的限制。 Edge 公有云和私有云用户

常见诊断步骤

使用以下工具/技巧之一来诊断此错误：

API 监控

要使用 API Monitoring 诊断错误，请执行以下操作：

  1. 以拥有 适当角色的用户身份 登录 Apigee Edge 界面。

  2. 切换到您要调查问题的组织。

  3. 前往 Analyze > API Monitoring > Investigate 页面。
  4. 选择您发现错误的具体时间范围。
  5. 根据时间绘制故障代码。
  6. 选择一个包含错误代码 protocol.http.TooBigHeaders 和状态代码 431 的单元格，如下所示：

    （ 查看大图）

  7. 您将看到有关错误代码 protocol.http.TooBigHeaders 的信息，如下所示：

    （ 查看大图）

  8. 点击查看日志，然后展开失败请求所在的行：

    （ 查看大图）

  9. 在 Logs 窗口中，请注意以下详细信息：

    • 状态代码：431
    • 错误来源：apigee
    • 错误代码：protocol.http.TooBigHeaders。
    • 请求长度（字节）： 32150 (> 25 KB)
  10. 如果故障来源的值为 apigee 或 MP，则故障代码的值为 protocol.http.TooBigHeaders，请求长度大于 25 KB，这表明客户端应用作为 HTTP 请求的一部分发送的所有请求标头的总大小超过了 Apigee 中允许的限制。

跟踪工具

NGINX

如需使用 NGINX 访问日志诊断错误，请执行以下操作：

  1. 如果您是 Private Cloud 用户，则可以使用 NGINX 访问日志来确定有关 HTTP 431 错误的关键信息。

  2. 检查 NGINX 访问日志：

    /opt/apigee/var/log/edge-router/nginx/ORG~ENV.PORT#_access_log

    其中：将 ORG、ENV 和 PORT# 替换为实际值。

  3. 搜索以查看在特定持续时间内是否存在任何 431 错误（如果问题是在过去发生的），或者是否有任何请求仍然失败并显示 431。

  4. 如果您确实发现 X-Apigee-fault-code 与 X-Apigee-fault-code 的值匹配的任何 431 错误，则确定 X-Apigee-fault-code 的值。

    NGINX 访问日志中的上述示例条目具有 X-Apigee-fault-code 和 X-Apigee-fault-code 的以下值：

    响应标头 值
    X-Apigee-fault-code protocol.http.TooBigHeaders
    X-Apigee-fault-source MP

    注意请求长度：40159（40 KB 大于 25 KB，Apigee Edge 中的请求标头允许的上限）

    在上述示例日志条目中，X-Apigee-fault-source 的值为 apigee 或 MP，X-Apigee-fault-code 的值为 protocol.http.TooBigHeaders，请求长度为 40 KB，大于 Apigee 所允许的限制 - 25 KB。这清楚地表明客户端应用作为 HTTP 请求的一部分发送的所有请求标头的总大小超出了 Apigee Edge 中允许的 25 KB 限制。

原因：请求标头大小超出允许的上限

诊断

  1. 按照常见诊断步骤中所述，确定使用 API Monitoring 或 NGINX Access 日志观察到的错误的故障代码、故障来源和请求长度大小。
  2. 如果故障来源的值为 apigee 或 MP，故障代码的值为 protocol.http.TooBigHeaders，并且请求长度大于 25 KB，则表示客户端应用向 Apigee 发送的请求大小大于 Apigee Edge 中允许的限制。
  3. 您可以使用以下方法之一验证请求标头大小是否超过了允许的 25 KB 限制：

    错误消息

    如需使用错误消息进行验证，请执行以下操作：

    如果您有权访问从 Apigee Edge 收到的完整错误消息，请参阅 faultstring。faultstring 表示请求标头的总大小超出了允许的 25 KB 限制。

    示例错误消息：

    "faultstring":"request headers size exceeding 25,600"

    实际请求

    如需使用实际请求进行验证，请执行以下操作：

    如果您有权访问客户端应用发出的实际请求，请执行以下步骤：

    1. 验证请求中传递的标头大小。

    2. 如果您发现标头的总大小超过 Apigee Edge 中允许的限制，这就是问题的原因。

      示例请求：

      curl -v https://HOSTALIAS/test -H "header0: 000000000000000000……..000000<trimmed>" -H "header1: 111111111111111111……..111111<trimmed>" -H "header2: 222222222222222222……..222222<trimmed>"-H "header3: 333333333333333333……..333333<trimmed>"

      在上述情况中，标头 header0、header1、header2 和 header3 的总大小大于 25 KB，也就是说，它包含的 ASCII 字符（字节）超过了 25 K。

      如果您使用的是其他客户端，则可以查看客户端日志并尝试确定发送到 Apigee Edge 的请求行的大小。

    消息处理器日志

    如需使用消息处理器日志进行验证，请执行以下操作：

    如果您是 Private Cloud 用户，则可以使用消息处理器日志来验证请求标头大小是否超出了 Apigee Edge 中允许的限制。

    1. 检查消息处理器日志：

      /opt/apigee/var/log/edge-message-processor/logs/system.log

    2. 搜索以查看在特定持续时间内是否存在任何 431 错误（如果问题是在过去发生的），或者是否有任何请求仍然失败并显示 431。您可以使用以下搜索字符串。 
      grep -ri "exceeding"

      grep -ri "RequestHeadersTooLarge"
    3. 您会发现，system.log 中的行与以下内容类似： 
      2021-07-27 08:30:28,419  NIOThread@1 ERROR ADAPTORS.HTTP.FLOW -
AbstractRequestListener.onException() :
Request:GET, uri:/test/, message Id:null,
exception:com.apigee.errors.http.user.RequestHeadersTooLarge{
code = protocol.http.TooBigHeaders, message = request headers size
exceeding 25,600, associated contexts = []}, context:Context@9c5903
input=ClientInputChannel(SSLClientChannel[Accepted:
Remote:192.168.205.251:8443 Local:192.168.67.23:22188]@25130
useCount=1 bytesRead=0 bytesWritten=15367 age=667062ms  lastIO=0ms
isOpen=true)

      上述错误消息中的文本 message = request headers size exceeding 25,600 表示请求标头总大小超过 25 KB。因此，Apigee Edge 会抛出 com.apigee.errors.http.user.RequestHeadersTooLarge 异常并将带有错误代码 protocol.http.TooBigHeaders 的 431 状态代码返回给客户端应用。

分辨率

修正尺寸

方法 1 [推荐]：解决客户端应用，不发送总大小超过允许限制的请求标头

  1. 分析特定客户端发送大小较大的请求标头的原因，导致总标头大小超过限制中定义的允许的上限。

  2. 如果不希望这样，请修改您的客户端应用，使其发送的请求标头的大小小于允许的上限。

    在上述示例中，您可以通过将长标头值参数作为请求正文/载荷的一部分进行传递来解决此问题：

    curl -v https://HOSTALIAS/test -d '{ "header0: 000000000000000000……..000000<trimmed>" , "header1: 111111111111111111……..111111<ttrimmed>" , "header2: 222222222222222222……..222222<ttrimmed>", "header3: 333333333333333333……..333333<ttrimmed>" }'
  3. 如果需要，并且想要发送的标头超出允许的上限，请转到下一个选项。

CwC

方法 2：使用 CwC 媒体资源提高请求行数量上限

Apigee 提供了 CwC 属性，可用于提高请求行大小限制。如需了解详情，请参阅 在消息处理器上设置请求行数上限

限制

Apigee 要求客户端应用和后端服务器不会发送大小超过 Apigee Edge 限制中针对请求/响应标头大小限制所允许的限制的请求/响应标头。

  1. 如果您是公有云用户，则请求和响应标头大小的上限如 Apigee Edge 限制中的请求/响应标头大小中所述。
  2. 如果您是 Private Cloud 用户 ，则可能修改了请求和响应标头的默认上限（尽管不建议这样做）。您可以按照如何查看当前限制中的说明确定请求标头的大小上限。

如何查看当前的上限？

本部分介绍如何验证属性 HTTPRequest.headers.limit 是否已使用消息处理器上的新值更新。

  1. 在消息处理器计算机上，在 /opt/apigee/edge-message-processor/conf 目录中搜索属性 HTTPRequest.headers.limit，然后检查设置的值，如下所示： 
    grep -ri "HTTPRequest.headers.limit" /opt/apigee/edge-message-processor/conf
  2. 上述命令的示例结果如下所示： 
    /opt/apigee/edge-message-processor/conf/http.properties:HTTPRequest.headers.limit=25k

  3. 请注意，在上面的示例输出中，属性 HTTPRequest.headers.limit 已使用 http.properties 的值 25k 进行了设置。

    这表示在 Apigee for Private Cloud 中配置的请求标头大小限制为 25 KB。

规范

Apigee Edge 要求客户端应用不要在请求期间发送大大小的标头。如果请求包含的标头总大小超过指定限制，则 Apigee 会根据以下 RFC 规范抛出 431 Request Header Fields Too Large ：

规范
RFC 6585，第 5 节：431 请求标头字段过大

如果您仍然需要 Apigee 支持的任何帮助，请参阅必须收集诊断信息。

必须收集的诊断信息

收集以下诊断信息，然后联系 Apigee Edge 支持团队：

如果您是公有云用户，请提供以下信息：

  • 组织名称
  • 环境名称
  • API 代理名称
  • 完成用于重现 431 错误的 curl 命令
  • API 请求的跟踪文件

如果您是 Private Cloud 用户，请提供以下信息：

  • 观察到失败请求的完整错误消息
  • 组织名称
  • 环境名称
  • API 代理软件包
  • 失败 API 请求的跟踪文件
  • 完成用于重现 431 错误的 curl 命令

  • NGINX 访问日志 /opt/apigee/var/log/edge-router/nginx/ORG~ENV.PORT#_access_log

    其中：将 ORG、ENV 和 PORT# 替换为实际值。

  • 消息处理器系统日志 /opt/apigee/var/log/edge-message-processor/logs/system.log