503 Service Unavailable - Backend Server  |  Apigee Edge  |  Apigee Docs (2024)

Trace tool

1. Enable the trace session, and make the API call to reproduce the issue - 503 Service Unavailable.
2. Select one of the failing requests and examine the trace.
3. Navigate through various phases of the trace and locate where the failure occurred.
4. If you find that the 503 error is returned as a response from the target server, the cause for 503 error is the target server.

   Here’s a sample trace screenshot showing 503 Service Unavailable response received from the target server:

   
5. Click the Response received from target server phase and go through the Response Headers and Response Content sections to see if they have any useful information:
   • The Response Headers may contain the Server header, which indicates where the error response was sent from.
   • The Response Content may contain additional information about why the target server sent the 503 response code.
   
6. Confirm that the 503 error is coming from the target server by checking the values of X-Apigee-fault-source and X-Apigee-fault-code in the AX (Analytics Data Recorded) Phase in the trace using the steps given below:
   1. Click on AX (Analytics Data Recorded) Phase as shown in the screenshot below:
   2. Scroll down the Phase Details to the Response Headers section and determine the values of X-Apigee-fault-code and X-Apigee-fault-source as shown below:
   3. If the values of X-Apigee-fault-source and X-Apigee-fault-code match the values shown in the below table, you can confirm that the 503 error is coming from the target server:

      Response Headers	Value
      X-Apigee-fault-source	target
      X-Apigee-fault-code	messaging.adaptors.http.flow.ErrorResponseCode

7. Check if you are using proxy chaining i.e. if the target server/target endpoint is invoking another proxy in Apigee. To determine this:
   1. Navigate back to the Request sent to target server phase and click the Show Curl button and determine the target server host alias.
   2. If the target server host alias is pointing to a virtual host alias, then it's proxy chaining. In this case, you need to repeat all the above steps for the chained proxy till you determine what is actually causing the 503 Service Unavailable error. In these cases 503 Service Unavailable may happen in other chained proxies at other stages as well which can be diagnosed using this playbook.
   3. If the target server host alias points to your backend server, then go to Resolution.

NGINX access logs

You can also refer to NGINX lccess logs to determine whether the 503 status code was sent by the backend server. This is particularly useful if the issue has occurred in the past or if the issue is intermittent and you are unable to capture the trace in UI. Use the following steps to determine this information from NGINX access logs:

1. Check the NGINX access logs.

   /opt/apigee/var/log/edge-router/nginx/<org>~<env>.<port#>_access_log

2. Search for any 503 Errors for the specific API proxy during a specific duration (if the problem happened in the past) or for any requests still failing with 503.
3. If there are any 503 Errors, then check if the error is coming from the backend server. If the values of X-Apigee-fault-source and X-Apigee-fault-code match the values shown in the table below, the 503 error is coming from the backend server:

   Response Headers	Value
   X-Apigee-fault-source	target
   X-Apigee-fault-code	messaging.adaptors.http.flow.ErrorResponseCode

   Here's a sample entry showing the 503 error caused by the target server:

   
4. Review the specific API Proxy and ensure that you are using proxy chaining i.e., if the target server/target endpoint is not invoking another proxy in Apigee. If you are using proxy chaining, you need to repeat all the above steps for the chained proxy until you determine what is actually causing the 503 Service Unavailable error. In these cases, 503 Service Unavailable may happen in other chained proxies at other stages as well, which you can diagnose using this playbook.
5. If you confirm that you are not using proxy chaining, and the 503 error is coming from your backend server, then go to Resolution.

Call to Backend Server

You can make a direct call to the backend server and verify that you are getting the same 503 Service Unavailable response as received when the request was made through Apigee Edge.

1. Ensure that you have all the required headers, query parameters and any credentials that need to be passed to the backend server as part of the request.
2. If the backend service is publicly accessible, you can use the curl command, Postman or any other REST Client and invoke the backend server API directly.
3. If the backend server is accessible only from the Message Processors, you can use the curl command, Postman or any other REST Client and invoke the backend server API directly from the Message Processor.
4. Verify that the backend service is indeed returning 503 Service Unavailable error.