You're viewing **Apigee Edge** documentation.  
[Go to the
**Apigee X** documentation](http://cloud.google.com/apigee/docs/api-platform/errorcatalog/mp-runtime-errorcatalog). 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"
      }
   }
}
```

> [!NOTE]
> **Note:** Note that the `faultstring` in the above error message contains the limit allowed for the request headers in Apigee Edge, which is `25600` bytes (25 KB).

## 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](https://docs.apigee.com/api-platform/troubleshoot/runtime/431-toobigheaders.md.txt#limits) as per
[RFC 6585, section 5: 431 Request Header Fields Too Large](https://datatracker.ietf.org/doc/html/rfc6585#section-5).


Here are the possible causes for this error:

| Cause | Description | Troubleshooting instructions applicable for |
|---|---|---|
| [Request Headers size is greater than allowed limit](https://docs.apigee.com/api-platform/troubleshoot/runtime/431-toobigheaders.md.txt#request-greater) | 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](https://docs.apigee.com/api-platform/troubleshoot/runtime/431-toobigheaders.md.txt#limits). | Edge Public and Private Cloud users |

## Common diagnosis steps


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

### API Monitoring

> [!NOTE]
> **Note:** The instructions in this section are applicable for Public Cloud users only.


To diagnose the error using API Monitoring:

1. [Sign in to Apigee Edge UI](https://docs.apigee.com/api-platform/get-started/sign-in-manage-account.md.txt#sign_in_to_your_apigee_edge_account) as a user with an [appropriate role](https://docs.apigee.com/api-monitoring/access.md.txt#roles).
2. Switch to the organization in which you want to investigate the issue.

   ![](https://docs.apigee.com/static/api-platform/images/ts-431-toobigheaders-orgs.png)
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](https://docs.apigee.com/static/api-platform/images/431-toobigheaders-fault-code-cell.png))
   ![](https://docs.apigee.com/static/api-platform/images/ts-431-toobigheaders-fault-code-cell.png)
7. You will see the information about the fault code `protocol.http.TooBigHeaders`
   as shown below:

   ([view larger image](https://docs.apigee.com/static/api-platform/images/ts-431-toobigheaders-fault-code-info.png))
   ![](https://docs.apigee.com/static/api-platform/images/ts-431-toobigheaders-fault-code-info.png)
8. Click **View logs** and expand the row for the failed request:

   ([view larger image](https://docs.apigee.com/static/api-platform/images/ts-431-toobigheaders-logs.png))
   ![](https://docs.apigee.com/static/api-platform/images/ts-431-toobigheaders-logs.png)
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](https://docs.apigee.com/api-platform/troubleshoot/runtime/431-toobigheaders.md.txt#limits).

    > [!NOTE]
    > **Note:** The Request Length in API Monitoring indicates the sum of the size of all the requests headers and the payload.

### Trace tool

> [!NOTE]
> **Note:** The requests failing with this error can not be captured in the [Trace Tool](https://docs.apigee.com/api-platform/debug/using-trace-tool-0.md.txt), since the Message Processor performs the validations in a very early phase much before processing the request and executing any policy in the API Proxy.

### NGINX

> [!NOTE]
> **Note:** The instructions in this section are for Edge Private Cloud users only.


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:** <var translate="no">ORG</var>, <var translate="no">ENV</var>, and <var translate="no">PORT#</var> 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.**

   ![](https://docs.apigee.com/static/api-platform/images/ts-431-toobigheaders-nginx.png)

   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.

   > [!NOTE]
   > **Note:** The field Request Length in the NGINX Access Logs indicates the sum of the size of all the requests headers and the payload.

## 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](https://docs.apigee.com/api-platform/troubleshoot/runtime/431-toobigheaders.md.txt#common).
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](https://docs.apigee.com/api-platform/troubleshoot/runtime/431-toobigheaders.md.txt#limits).
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](https://docs.apigee.com/api-platform/troubleshoot/runtime/431-toobigheaders.md.txt#limits), 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:

   > [!NOTE]
   > **Note:** The instructions in this section are for Edge Private Cloud users only.

   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](https://docs.apigee.com/api-platform/troubleshoot/runtime/431-toobigheaders.md.txt#limits).
   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

> [!WARNING]
> **Warning:** Sending a request header size greater than 25 KB, the allowed limit in Apigee Edge, can lead to increased latency, performance issues, and timeouts. It is always recommended to send a header size less than 25 KB through Apigee Edge. Refer to the solutions listed below and use the recommended option only.


### Fix size

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

> [!NOTE]
> **Note:** This is the recommended option to fix this issue.

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](https://docs.apigee.com/api-platform/troubleshoot/runtime/431-toobigheaders.md.txt#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**

> [!NOTE]
> **Note:**
>
> 1. This is applicable only for Private Cloud customers.
> 2. This option should only be used when you cannot use any of the recommended options as there might be performance issues if the default size is increased.

Apigee provides a [CwC](https://docs.apigee.com/private-cloud/latest/how-configure-edge) property which allows it to increase the request line size limit.
For details see
[Set the request line limit on the Message Processor](https://docs.apigee.com/private-cloud/latest/setting-http-requestresponse-header-limits#configuring-limits-for-the-message-processor)

> [!WARNING]
> **Warning:** While this option can help you work around the 25 KB request header limit enforced by the product, Apigee doesn't recommend that you increase the limit and can't support issues such as performance issues and timeouts that arise due to exceeding that limit.

## 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](https://docs.apigee.com/api-platform/reference/limits.md.txt#system).

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](https://docs.apigee.com/api-platform/reference/limits.md.txt#system).
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](https://docs.apigee.com/api-platform/troubleshoot/runtime/431-toobigheaders.md.txt#check-limit).

### How to check the current limit?

> [!NOTE]
> **Note:** The instructions in this section are for Edge Private Cloud users only.


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](https://datatracker.ietf.org/doc/html/rfc6585#section-5) |

If you still need any assistance from Apigee Support, go to
[Must gather diagnostic information](https://docs.apigee.com/api-platform/troubleshoot/runtime/431-toobigheaders.md.txt#must-gather).

## Must gather diagnostic information

Gather the following diagnostic information, and then contact [Apigee Edge Support](https://docs.apigee.com/api-platform/troubleshoot/support.md.txt):

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:** <var translate="no">ORG</var>, <var translate="no">ENV</var> and <var translate="no">PORT#</var> are replaced with
  actual values.
- Message Processor system logs `/opt/apigee/var/log/edge-message-processor/logs/system.log`