431 Request Header Fields Too Large - TooBigHeaders

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation.
info

Symptom

The client application gets an HTTP status code of 431 Request Header Fields Too Large with error code protocol.http.TooBigHeaders as a response for API calls.

Error message

Client application gets the following response code:

HTTP/1.1 431 Request Header Fields Too Large

In addition, you may observe the following error message:

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

Possible causes

This error occurs if the total size of all the request headers sent by the client application to Apigee Edge as part of the HTTP request is greater than the allowed limit in Apigee Edge as per RFC 6585, section 5: 431 Request Header Fields Too Large.

Here are the possible causes for this error:

Cause Description Troubleshooting instructions applicable for
Request Headers size is greater than allowed limit The total size of all the headers sent by the client application as part of the HTTP request to Apigee Edge is greater than the allowed limit in Apigee Edge. Edge Public and Private Cloud users

Common diagnosis steps

Use one of the following tools/techniques to diagnose this error:

API Monitoring

To diagnose the error using API Monitoring:

  1. Sign in to Apigee Edge UI as a user with an appropriate role.
  2. Switch to the organization in which you want to investigate the issue.

  3. Navigate to the Analyze > API Monitoring > Investigate page.
  4. Select the specific timeframe in which you observed the errors.
  5. Plot Fault Code against Time.
  6. Select a cell which has the fault code protocol.http.TooBigHeaders and status code 431 as shown below:

    ( view larger image)

  7. You will see the information about the fault code protocol.http.TooBigHeaders as shown below:

    ( view larger image)

  8. Click View logs and expand the row for the failed request:

    ( view larger image)

  9. From the Logs window, note the following details:

    • Status Code: 431
    • Fault Source: apigee
    • Fault Code: protocol.http.TooBigHeaders.
    • Request Length(bytes): 32150 (> 25 KB)
  10. If the Fault Source has the value apigee or MP, the Fault Code has the value protocol.http.TooBigHeaders and Request Length is more than 25 KB then that indicates that the total size of all request headers sent by the client application as part of HTTP request greater than the allowed limit in Apigee.

Trace tool

NGINX

To diagnose the error using NGINX access logs:

  1. If you are a Private Cloud user, then you can use NGINX access logs to determine the key information about HTTP 431 errors.
  2. Check the NGINX access logs:

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

    Where: ORG, ENV, and PORT# are replaced with actual values.

  3. Search to see if there are any 431 errors during a specific duration (if the problem happened in the past) or if there are any requests still failing with 431.
  4. If you do find any 431 errors with the X-Apigee-fault-code matching the value of protocol.http.TooBigHeaders, then determine the value of the X-Apigee-fault-source.

    The above sample entry from the NGINX access log has the following values for X-Apigee-fault-code and X-Apigee-fault-source:

    Response Headers Value
    X-Apigee-fault-code protocol.http.TooBigHeaders
    X-Apigee-fault-source MP

    Note the Request Length: 40159 (40 KB is greater than 25 KB, the allowed limit for request headers in Apigee Edge)

    In the above sample log entry, the X-Apigee-fault-source has the value apigee or MP, the X-Apigee-fault-code has the value protocol.http.TooBigHeaders and Request Length is 40 KB, which is greater than the allowed limit in Apigee - 25 KB. This clearly indicates that the total size of all request headers sent by the client application as part of HTTP request has exceeded the allowed limit of 25 KB in Apigee Edge.

Cause: Request Headers size is greater than allowed limit

Diagnosis

  1. Determine the Fault Code, Fault Source and Request-Length size for the error observed using API Monitoring or NGINX Access logs as explained in Common diagnosis steps.
  2. If the Fault Source has the value apigee or MP, the Fault Code has the value protocol.http.TooBigHeaders, and Request Length is more than 25 KB, then this indicates that the request size sent by the client application to Apigee is greater than the allowed limit in Apigee Edge.
  3. You can validate that the request headers size has exceeded the 25 KB allowed limit using one of the following methods:

    Error message

    To validate using the error message:

    If you have access to the complete error message received from Apigee Edge, then refer to the faultstring. The faultstring indicates that the total size of the Request Headers has exceeded the allowed limit of 25 KB.

    Sample error message:

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

    Actual request

    To validate using the actual request:

    If you have access to the actual request made by the client application, then perform the following steps:

    1. Verify the size of the headers passed in the request.
    2. If you find that the total size of the headers is more than the allowed limit in Apigee Edge, then that is the cause of the issue.

      Sample request:

      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>"
      

      In the above case, the total size of the headers header0, header1, header2, and header3 is greater than 25 KB, that is, it contains more than 25 K ASCII characters (bytes).

      If you are using some other client, you can review the client logs and try to find out the size of the request line being sent to Apigee Edge.

    Message Processor logs

    To validate using Message Processor logs:

    If you are a Private Cloud user, then you can use Message Processor logs to validate if the Request Headers size has exceeded the allowed limit in Apigee Edge.

    1. Check the Message Processor logs:

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

    2. Search to see if there are any 431 errors during a specific duration (if the problem happened in the past) or if there are any requests still failing with 431. You may use the following search strings.
      grep -ri "exceeding"
      
      grep -ri "RequestHeadersTooLarge"
      
    3. You will find lines from system.log similar to the following:
      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)
      

      The text message = request headers size exceeding 25,600 in the above error message indicates that the total Request Headers size is more than 25 KB. Therefore, Apigee Edge throws the exception com.apigee.errors.http.user.RequestHeadersTooLarge and returns 431 status code with fault code protocol.http.TooBigHeaders to client applications.

Resolution

Fix size

Option #1 [Recommended]: Fix the client application not to send request headers with total size greater than the allowed limit

  1. Analyze the reason for the specific client to send Request Header with large size which makes total header size more than allowed limit as defined in Limits.
  2. If it is not desirable, modify your client application so that it sends Request Headers of a size less than the allowed limit.

    In the example discussed above, you can fix the issue by passing the long header values parameter as part of the request body/payload:

    curl -v https://HOSTALIAS/test -d '{ "header0: 000000000000000000……..000000<trimmed>" , "header1: 111111111111111111……..111111<ttrimmed>" , "header2: 222222222222222222……..222222<ttrimmed>", "header3: 333333333333333333……..333333<ttrimmed>" }'
    
  3. If it is desirable and you want to send a header more than the allowed limit, go to the next option.

CwC

Option #2 : Use CwC property to increase the request line limit

Apigee provides a CwC property which allows it to increase the request line size limit. For details see Set the request line limit on the Message Processor

Limits

Apigee expects the client application and backend server do not send Request/Response Headers whose sizes are greater than the allowed limit as documented for Request/Response Header Size Limit in Apigee Edge Limits.

  1. If you are a Public Cloud user, then the maximum limit for Request and Response Headers size is as documented for Request/Response Header size in Apigee Edge Limits.
  2. If you are a Private Cloud user, then you may have modified the default maximum limit for Request and Response Headers size (even though it is not a recommended practice). You can determine the maximum Request Header size limit by following instructions in How to check the current limit.

How to check the current limit?

This section explains how to verify that the property HTTPRequest.headers.limit has been updated with a new value on the Message Processors.

  1. On the Message Processor machine, search for the property HTTPRequest.headers.limit in the /opt/apigee/edge-message-processor/conf directory and check to see what value has been set as shown below:
    grep -ri "HTTPRequest.headers.limit" /opt/apigee/edge-message-processor/conf
    
  2. The sample result from the above command is as follows:
    /opt/apigee/edge-message-processor/conf/http.properties:HTTPRequest.headers.limit=25k
    
  3. In the example output above, note that the property HTTPRequest.headers.limit has been set with the value 25k in http.properties.

    This indicates that the limit for the Request Header size configured in Apigee for Private Cloud is 25 KB.

Specification

Apigee Edge expects the client application to not send headers of large size as part of the request. In case the request contains headers with total size more than the specified limit, Apigee throws 431 Request Header Fields Too Large according to the following RFC specifications:

Specification
RFC 6585, section 5: 431 Request Header Fields Too Large

If you still need any assistance from Apigee Support, go to Must gather diagnostic information.

Must gather diagnostic information

Gather the following diagnostic information, and then contact Apigee Edge Support:

If you are a Public Cloud user, provide the following information:

  • Organization name
  • Environment name
  • API Proxy name
  • Complete curl command used to reproduce the 431 error
  • Trace file for the API requests

If you are a Private Cloud user, provide the following information:

  • Complete error message observed for the failing requests
  • Organization name
  • Environment name
  • API Proxy bundle
  • Trace file for the failing API requests
  • Complete curl command used to reproduce the 431 error
  • NGINX access logs /opt/apigee/var/log/edge-router/nginx/ORG~ENV.PORT#_access_log

    Where: ORG, ENV and PORT# are replaced with actual values.

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