You're viewing **Apigee Edge** documentation.  
[Go to the
**Apigee X** documentation](http://cloud.google.com/apigee/docs). info

Step through a sample scenario that demonstrates how to troubleshoot 5xx issues with your APIs.

> [!NOTE]
> **Note:**While this example demonstrates how to troubleshoot 5xx issues, you can use this same process to troubleshoot any type of issue.

| # | Step | Description |
|---|---|---|
| 1 | [Monitor recent API traffic](https://docs.apigee.com/api-monitoring/sample-scenarios#recent-5xx) | View the recent API monitoring data for all API proxies and targets that have had traffic in the last hour. Drill down on API proxies or targets with a high error % rate. |
| 2 | [Identify trends in your API monitoring data](https://docs.apigee.com/api-monitoring/sample-scenarios#timeline-5xx) | Access an historical view of your API monitoring data up to the last 3 months to gain a broader perspective. |
| 3 | [Investigate 5xx issues](https://docs.apigee.com/api-monitoring/sample-scenarios#investigate-5xx) | View the fault codes that are experiencing the highest relative volumes over time to further investigate the source of the 5xx issues. (Typically, 5xx status codes can be classified using one or more fault codes.) |
| 4 | [Set up a 5xx alert](https://docs.apigee.com/api-monitoring/sample-scenarios#setup-alert-5xx) | Set up an alert to be notified when the number of 5xx status codes exceeds a particular threshold. |
| 5 | [Generate a custom report with client details](https://docs.apigee.com/api-monitoring/sample-scenarios#custom-report-5xx) (Optional) | Optionally generate a custom report to identify details about the client that is triggering the 5xx errors. **Note** : You must be an **organization administrator** to generate a custom report. |
| 6 | [Group API proxies into a collection](https://docs.apigee.com/api-monitoring/sample-scenarios#collection-5xx) | Create a collection to group API proxies and set up appropriate alert threshold values for all members of the group to diagnose issues faster. |
| 7 | [Resolve the 5xx issues](https://docs.apigee.com/api-monitoring/sample-scenarios#resolve-5xx) | Based on your investigation and diagnosis, take appropriate actions to resolve the 5xx issues. |

## Step 1: Monitor recent API traffic

To view API monitoring data for the API proxies and targets that have had traffic over the last hour:

1. Select **Analyze \> API Monitoring \> Recent** in the Edge UI to access the Recent dashboard.
2. Notice the API proxies and targets that have had a high error % rate over the last hour.  

   ![](https://docs.apigee.com/static/api-monitoring/images/sample-5xx-recent-noerrors.png)

   > [!NOTE]
   > **Note** : If the API proxy does not have a value, does not apply, or cannot be determined, the dashboard will display **"not set"** as the origin. For more information, see [Why do I see "not set" in the dashboards?](https://docs.apigee.com/api-monitoring/faq#not-set)

3. Click the API proxy or target with a high error % rate to view details in the right pane. Notice the high percentage of **5xx errors** in this example.

   ![](https://docs.apigee.com/static/api-monitoring/images/sample-5xx-recentdetails.png)

For more information about this step, see [Monitor recent API traffic](https://docs.apigee.com/api-monitoring/recent).

## Step 2: Identify trends in your API monitoring data

To access an historical view of API monitoring data for the API proxies and targets that have had traffic up to the last three months:

1. In the right pane of the Recent dashboard, select **![More menu](https://docs.apigee.com/static/api-monitoring/images/more-menu.png) \> View in Timeline** to access the Timeline dashboard. Alternatively, you can click **Analyze \> API Monitoring \> Timeline** in the Edge UI.  
   ![](https://docs.apigee.com/static/api-monitoring/images/sample-5xx-view-timeline.png)
2. View the trend for the API proxy or target over time. Notice that the trend has been consistent over the last 7 days. ![](https://docs.apigee.com/static/api-monitoring/images/sample-5xx-timeline.png)

For more information about this step, see [Identify trends in your API monitoring data](https://docs.apigee.com/api-monitoring/timeline).

## Step 3: Investigate 5xx issues

Apigee provides a set of [fault codes](https://docs.apigee.com/api-monitoring/fault-codes) that help you to diagnose issues. Typically, 5xx status codes can be classified using one or more fault codes.

To investigate 5xx issues:

1. In the right pane of the Timeline dashboard, select **![More menu](https://docs.apigee.com/static/api-monitoring/images/more-menu.png) \> View in Investigate** to access the Investigate dashboard. Alternatively, you can click **Analyze \> API Monitoring \> Investigate** in the Edge UI.  
   ![](https://docs.apigee.com/static/api-monitoring/images/sample-5xx-viewinvestigate.png)  
   The Investigate dashboard enables you to compare relational activity between metrics, such as fault code versus time.
2. View the **fault code versus time matrix** to view the fault code activity over the last hour. Notice the fault codes that are experiencing the highest relative volumes based on the color shading of a block. The darker the block, the higher the relative volume.

   For example, the `policies.ratelimit.SpikeArrestViolation` and `policies.ratelimit.QuotaViolation` fault codes are showing a higher relative volume in the following matrix:
   ![Fault codes](https://docs.apigee.com/static/api-monitoring/images/sample-faultcodes.png)
3. Click the darkest block (first block) in the `policies.ratelimit.SpikeArrestViolation` row to view more details in the right pane.  

   ![](https://docs.apigee.com/static/api-monitoring/images/sample-5xx-investigate-detail.png)

4. Notice that the fault source is the **perfBenchmark_invalid_v1** API proxy and the HTTP Status code is **500** . A [500 status code](https://docs.apigee.com/api-platform/reference/policies/spike-arrest-policy#runtime-errors) is a common runtime error code for Spike Arrest policy violations.

5. View the Distribution by Developer App, just below the Suspected cause panel, to identify the developer apps with the highest error rates.  

   ![](https://docs.apigee.com/static/api-monitoring/images/distribution-by-devapp.png)

For more information about this step, see [Identify issues](https://docs.apigee.com/api-monitoring/investigate).

## Step 4: Set up 5xx alert

Set up an alert based on the selected context in the Investigate details pane to be notified when the number of 5xx status codes exceeds a specific threshold.

1. In the right pane of the Investigate dashboard, select **![More menu](https://docs.apigee.com/static/api-monitoring/images/more-menu.png) \> Create Alert** .
   ![](https://docs.apigee.com/static/api-monitoring/images/sample-5xx-create-alert.png)

2. Complete the fields in the alert dialog. The condition fields are pre-populated with data from the current context. For example:

   ![](https://docs.apigee.com/static/api-monitoring/images/sample-5xx-alert.png)
3. Click **Save**.

In the future, when the 5xx error rate exceeds 5% for a period of 5 minutes for the **perfBenchmark_invalid_v1** API proxy, a **notification** is sent to the specified email and a **visual alert** is displayed in the UI. For example:

![](https://docs.apigee.com/static/api-monitoring/images/identify-alerts.png)

For more information about this step, see [Set up alerts and notifications](https://docs.apigee.com/api-monitoring/alerts-notifications).

## Step 5: Generate a custom report with client details (Optional)

> [!NOTE]
> **Note** : You must be an **organization administrator** to generate a custom report.

Optionally, generate a custom report to identify more details about the client that is triggering the 5xx errors.

On the [Reports page](https://docs.apigee.com/api-platform/analytics/create-custom-reports#viewingallcustomreports), custom reports that are created based on an alert are named using the following format: `API Monitoring Generated: *alert-name*`.

1. Access the custom report created when setting up the alert in one of the following ways:

   - Select **Analyze \> Custom Reports \> Reports** in the left navigation bar to display the Reports page. Click the name of the report in the list: **API Monitoring Generated: 5xx Alert**

   - Click within the notification that is displayed when the alert is created. For example:

   ![](https://docs.apigee.com/static/api-monitoring/images/report-notification.png)
2. Add the following dimensions:

   - Developer App
   - Client ID
   - Client IP Address

   ![](https://docs.apigee.com/static/api-monitoring/images/sample-5xx-report.png)
3. To view a report based on a specific developer app with a high error rate, add a filter similar to the following:

   `and (developer_app eq 'perfBenchmarkApp0')`

   **Note**: In this case, remove Developer App from the list of dimensions.
4. Click **Save**.

5. [Run the report](https://docs.apigee.com/api-platform/analytics/create-custom-reports#run) to view details about the developer app and clients that are triggering the 5xx status code.

For more information about this step, see [Create custom reports](https://docs.apigee.com/api-monitoring/custom-report).

## Step 6: Group API proxies into a collection

Create a collection to group API proxies and set up appropriate alert threshold values for all members of the group to diagnose issues faster.

1. Select **Analyze \> API Monitoring \> Collections** in the Edge UI to display the Collections dashboard.
2. Click **+ Collection**.
3. Select **Proxy**.
4. Select the **prod** from the environment drop-down.
5. Click **Next**.
6. Complete the fields in the collection dialog.  
   ![](https://docs.apigee.com/static/api-monitoring/images/sample-5xx-collection.png)
7. Click **Save**

Next, you can [set up an alert](https://docs.apigee.com/api-monitoring/alerts-notifications#add), similar to step 4, and set the **dimension** to the collection that you defined above.

![](https://docs.apigee.com/static/api-monitoring/images/5xx-errorrate-example.png)

For more information about this step, see [Manage collections](https://docs.apigee.com/api-monitoring/collections).

## Step 7: Resolve the 5xx issues

Take the appropriate actions to resolve the 5xx issues. For example, based on your diagnosis you might perform one of the following tasks:

- Use [Apigee Sense](https://docs.apigee.com/sense/what-apigee-sense) to determine if the spike in requests is suspicious and decide you want to block the client IP address identified in the custom report.
- Add a [quota policy](https://docs.apigee.com/api-platform/reference/policies/quota-policy) to limit the number of connections developer apps can make to your API proxy over a specific period of time.
- [Monetize your API](https://docs.apigee.com/api-platform/monetization/basics-monetization) to charge developers for usage over a certain number of calls.