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:

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

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