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 `502 Bad Gateway` with
error code `protocol.http.TooBigHeaders `as a response for API
calls.
## Error message
Client application gets the following response code:
```
HTTP/1.1 502 Bad Gateway
```
In addition, you may observe the following error message:
```
{
"fault":{
"faultstring":"response headers size exceeding 25,600",
"detail":{
"errorcode":"protocol.http.TooBigHeaders"
}
}
}
```
## Possible causes
This error occurs if the total size of the headers sent by the target/backend
server to Apigee Edge as part of the HTTP response is greater than the allowed
[allowed limit in Apigee Edge](https://docs.apigee.com/api-platform/troubleshoot/runtime/502-toobigheaders#limits).
Here are the possible causes for this error:
| Cause | Description | Troubleshooting instructions applicable for |
|---|---|---|
| [Size of headers in the response is greater than allowed limit](https://docs.apigee.com/api-platform/troubleshoot/runtime/502-toobigheaders#request-greater) | The header size of a particular header or the sum of the header sizes of all the headers sent by the target/backend server as part of HTTP response to Apigee Edge is more than the [allowed limit in Apigee Edge](https://docs.apigee.com/api-platform/troubleshoot/runtime/502-toobigheaders#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#sign_in_to_your_apigee_edge_account) as a user with an [appropriate role](https://docs.apigee.com/api-monitoring/access#roles).
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. You may select the **Proxy** filter to narrow down the fault code.
6. Plot **Fault Code** against **Time**.
7. Select a cell which has the fault code `protocol.http.TooBigHeaders` as
shown below:
([view larger image](https://docs.apigee.com/static/api-platform/images/ts-502-toobigheaders-fault-code-cell.png))
8. 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-502-toobigheaders-fault-code-info.png))
9. Click **View logs** and expand the row for the failed request.
([view larger image](https://docs.apigee.com/static/api-platform/images/ts-502-toobigheaders-logs.png))
10. From the **Logs** window, note the following details:
- **Status Code:** `502`
- **Fault Source:** `target`
- **Fault Code:** `protocol.http.TooBigHeaders`.
11. If the **Fault Source** has the value `target` and the **Fault
Code** has the value `protocol.http.TooBigHeaders`, then that indicates that the HTTP response from the target/ backend server has headers whose size is greater than the [allowed limit in Apigee Edge](https://docs.apigee.com/api-platform/troubleshoot/runtime/502-toobigheaders#limits).
### Trace tool
> [!NOTE]
> **Note:** The instructions in this section are applicable for Public and Private Cloud users.
1. Enable the [trace session](https://docs.apigee.com/api-platform/debug/using-trace-tool-0) and either:
1. Wait for the `502 Bad Gateway` error to occur, or
2. If you can reproduce the issue, make the API call and reproduce `502 Bad
Gateway` error.
2. Select one of the failing requests and examine the trace.
3. Navigate through different phases of the trace and locate where the failure occurred.
4. Typically you will see this error in the flow named **Error** just after the
**Request sent to target server** phase as shown below:
([view larger image](https://docs.apigee.com/static/api-platform/images/ts-502-toobigheaders-request-sent.png))
Note the values of the error from the trace:
- **error:** `response headers size exceeding 25,600`
- **error.class** : `com.apigee.errors.http.server.BadGateway`
This indicates that Apigee Edge (Message Processor component) throws the error as
soon as it receives the response from the backend server due to a header size
exceeding the allowed limit.
5. You would see the failure in the **Response Sent to Client**
error response sent by Apigee Edge as shown below:
([view larger image](https://docs.apigee.com/static/api-platform/images/ts-502-toobigheaders-response-sent.png))
6. Note the values of the error from the trace. The above sample trace shows:
- **Error:** `502 Bad Gateway`.
- **Error Content:** `{"fault":{"faultstring":"response headers size exceeding 25,600","detail":{"errorcode":"protocol.http.TooBigHeaders"}}}`
7. Navigate to the **AX** (Analytics Data Recorded) phase in the trace
and click on it to see the related details.
([view larger image](https://docs.apigee.com/static/api-platform/images/ts-502-toobigheaders-ax.png))
Note the value of the following:
| Error headers | Value |
|---|---|
| X-Apigee-fault-code | `protocol.http.TooBigHeaders` |
| X-Apigee-fault-source | `target` |
| Error Content: Body | `{"fault":{"faultstring":"response headers size exceeding 25,600","detail":{"errorcode":"protocol.http.TooBigHeaders"}}}` |
### 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 `502 Bad Gateway`.
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 `502` errors with error code `protocol.http.TooBigHeaders` during a specific duration (if the problem happened in the past) or if there are any requests still failing with `502`.
4. If you do find any `502` errors with the **X-Apigee-fault-code** matching the value of**`protocol.http.TooBigHeaders`** , then determine
the value of the **X-Apigee-fault-source.**
**Sample 502 error from NGINX access log:**
The above sample entry from the NGINX access log has the following values for
**X-Apigee-fault-code** and **X-Apigee-fault-source:**
| Error headers | Value |
|---|---|
| X-Apigee-fault-code | `protocol.http.TooBigHeaders` |
| X-Apigee-fault-source | `target` |
## Cause: Size of headers in the response is greater than allowed limit
### Diagnosis
1. Determine the **Fault Code** , **Fault Source** , and **Response Payload Size** for the error observed using API Monitoring, Trace tool, or NGINX Access logs as explained in [Common diagnosis steps](https://docs.apigee.com/api-platform/troubleshoot/runtime/502-toobigheaders#common).
2. If the **Fault Source** has the value `target`, then this indicates that the response sent by the target/backend server to Apigee has headers whose size is greater than the [allowed limit in Apigee Edge](https://docs.apigee.com/api-platform/troubleshoot/runtime/502-toobigheaders#limits).
3. You can validate that the response from the target/backend has headers whose size was greater than the 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 response header size has exceeded the allowed limit.
**Sample error message:**
```
"faultstring":"response headers size exceeding 25,600"
```
In the above error message, note in the `faultstring`that the
response has headers whose total size exceeds [the allowed limit](https://docs.apigee.com/api-platform/troubleshoot/runtime/502-toobigheaders#limits).
### Actual request
To validate using the actual request:
If you have access to the actual request made to the target/backend server,
then perform the following steps:
1. If you are a **Public Cloud/Private Cloud user**, make a request directly to the backend server from the backend server itself or any other machine from where you are allowed to make the request to the backend server.
2. If you are a **Private Cloud user**, you can also make the request to the backend server from one of the Message Processors.
3. Examine the response received from the backend server and specifically compute and verify the total size of the headers passed in the response.
4. If you find that the size of the headers in response payload
is more than the [allowed limit in Apigee Edge](https://docs.apigee.com/api-platform/troubleshoot/runtime/502-toobigheaders#limits),
then that is the cause of the issue.
**Sample response from the target server:**
```
curl -v https://TARGET_SERVER_HOST/test
```
* About to connect() to 10.1.0.10 port 9000 (#0)
* Trying 10.1.0.10...
* Connected to 10.1.0.10 (10.1.0.10) port 9000 (#0)
> GET /test HTTP/1.1
> User-Agent: curl/7.29.0
> Host: 10.1.0.10:9000
> Accept: */*
<
< HTTP/1.1 200 OK
< Accept-Ranges: bytes
< Content-Length: 0
< Content-Type: text/plain; charset=utf-8
< Last-Modified: Tue, 20 Jul 2021 09:23:56 GMT
< Testheader1: XVlBzgba------THctcuAx
< Testheader2: hxKQFDaFpLSj------FbcXoEFfRsWxP
< Date: Fri, 23 Jul 2021 09:51:22 GMT
<
* Connection #0 to host 10.1.0.10 left intact
In the above example, `Testheader1` and
`Testheader2` have higher sizes, which is the cause
for this error as it exceeds the [allowed limit in
Apigee Edge](https://docs.apigee.com/api-platform/troubleshoot/runtime/502-toobigheaders#limits).
> [!NOTE]
> **Note:** Apigee throws this error if the total size of all the headers in the backend server's response is greater than the [allowed limit in
> Apigee Edge](https://docs.apigee.com/api-platform/troubleshoot/runtime/502-toobigheaders#limits).
### 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 Response headers size has exceeded the
[allowed limit in Apigee Edge](https://docs.apigee.com/api-platform/troubleshoot/runtime/502-toobigheaders#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 `502` errors during a specific duration (if the problem happened in the past) or if there are any requests still failing with `502`. You may use the following search string:
```
grep -ri "response headers size exceeding"
```
3. You will find lines from `system.log` similar to the following. The response headers size may vary in your case:
```
2021-07-23 08:25:12,307 org:myorg env:prod api:bigheadertest rev:1
messageid:r23ijb1b-1 NIOThread@1 ERROR HTTP.CLIENT -
HTTPClient$Context$3.onException() : ClientChannel[Connected:
Remote:3.7.1.1:9000 Local:192.168.2.1:56098]@8414 useCount=1
bytesRead=0 bytesWritten=207 age=640ms lastIO=0ms isOpen=true.onExceptionRead
exception: {}
com.apigee.errors.http.server.BadGateway: response headers size exceeding 25,600
2021-07-23 08:25:12,307 org:myorg env:prod api:bigheadertest
rev:1 messageid:r23ijb1b-1 NIOThread@1 ERROR ADAPTORS.HTTP.FLOW -
AbstractResponseListener.onException() : AbstractResponseListener.onError
(HTTPResponse@31f3ef88, response headers size exceeding 25,600)
```
4. As soon as the Message Processor gets the response from the backend/target
server and finds that the total size of the headers is greater than 25 KB,
it stops and throws the error:
`response headers size exceeding 25,600`
It implies that the **Total Header Size** is more than 25 KB and Apigee
throws the error when the size starts to exceed the limit 25 KB with fault code
as `protocol.http.TooBigHeaders`
## Resolution
### Fix size
**Option #1 \[Recommended\]: Fix the target server application not to send headers size
exceeding the Apigee limit**
> [!NOTE]
> **Note:** This is the recommended option to fix this issue.
1. Analyze the reason for the specific target server to send response header size more than allowed limit as defined in [Limits](https://docs.apigee.com/api-platform/troubleshoot/runtime/502-toobigheaders#limits).
2. If it is not desirable, modify your backend server application so that it sends the Response headers whose size is less than the [allowed limit in
Apigee Edge](https://docs.apigee.com/api-platform/troubleshoot/runtime/502-toobigheaders#limits).
3. Check if the header information can be sent as part of the response body.
4. If feasible, send any large information that you were planning to send as part of the header in the response body. This will ensure that you will not exceed the response header limit.
> [!NOTE]
> **Note:** If you pass any large information that you had originally planned to send as part of the header in the response body, ensure that the recipient, that is the backend server, is modified appropriately to handle/parse/extract that information from the response body instead of the headers.
### CwC
**Option #2 : Use CwC property to increase the response header size limit**
> [!NOTE]
> **Note:** This is applicable only for Private Cloud customers.
Apigee provides a [CwC](https://docs.apigee.com/private-cloud/latest/how-configure-edge) property which allows it to increase the Response headers size limit.
For details see
[Configuring limits for 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 Response 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
header sizes greater than the allowed limit as documented
for Request/Response Header Size in
[Apigee Edge Limits](https://docs.apigee.com/api-platform/reference/limits#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#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 Response Header size limit by following instructions in [How to check the current limit](https://docs.apigee.com/api-platform/troubleshoot/runtime/502-toobigheaders#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 `HTTPResponse.headers.limit` has
been updated with a new value on the Message Processors.
1. On the Message Processor machine, search for the property `HTTPResponse.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 "HTTPResponse.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:HTTPResponse.headers.limit=25k
```
3. In the example output above, note that the property `HTTPResponse.headers.limit`
has been set with the value `25k` in `http.properties`.
This indicates that the limit for the Response payload size configured in Apigee for Private
Cloud is **25 KB.**
If you still need any assistance from Apigee Support, go to
[Must gather diagnostic information](https://docs.apigee.com/api-platform/troubleshoot/runtime/502-toobigheaders#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):
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 `502` error
- Trace file for the API requests
- Complete output of the response from target/backend server along with the size of the headers
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 `502` error
- Complete output of the response from target/backend server along with the size of the headers
- 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`