API Request Outcomes Sankey Diagram: Endpoints to Errors
Trace API requests from endpoint to status class to the cause of each error. See which endpoints produce failures and why, then replace the sample counts with your own logs.
An API outcomes Sankey follows requests from the endpoint that received them to success or an error class, then splits each error class by cause. It points at the endpoint and the cause worth fixing first.
The example has one million requests across four endpoints. Of these, 920 thousand succeed, 60 thousand are client errors (4xx) and 20 thousand are server errors (5xx). The last column gives the cause of each error: invalid input, expired token, not found and rate limiting on the client side; timeout, dependency failure and bug on the server side.
An error rate per endpoint is a single number. The Sankey keeps the route: Checkout has the highest server error rate in the example (7 of 150), and Login the highest client error rate (22 of 200). The figures are invented. Use counts for one window, and say whether retries are counted once or each time. The same idea for alerts rather than requests is /sankey/incident-response.
How to read this diagram
- 920 of 1,000 thousand requests (92%) succeed; 6% are client errors and 2% server errors.
- Checkout has the highest server error rate: 7 of 150 (about 5%).
- Login has the highest client error rate: 22 of 200 requests (11%). Expired tokens cause 20 of the 60 client errors.
- Half of the server errors (10 of 20) are timeouts.
The data behind it
Invented figures for illustration. Not data about any real company, team or system.
| From | To | Amount (thousand requests) |
|---|---|---|
| Search | Success (2xx) | 370 |
| Search | Client error (4xx) | 22 |
| Search | Server error (5xx) | 8 |
| Checkout | Success (2xx) | 135 |
| Checkout | Client error (4xx) | 8 |
| Checkout | Server error (5xx) | 7 |
| Login | Success (2xx) | 175 |
| Login | Client error (4xx) | 22 |
| Login | Server error (5xx) | 3 |
| Catalogue | Success (2xx) | 240 |
| Catalogue | Client error (4xx) | 8 |
| Catalogue | Server error (5xx) | 2 |
| Client error (4xx) | Invalid input | 25 |
| Client error (4xx) | Expired token | 20 |
| Client error (4xx) | Not found | 10 |
| Client error (4xx) | Rate limited | 5 |
| Server error (5xx) | Timeout | 10 |
| Server error (5xx) | Dependency failure | 6 |
| Server error (5xx) | Bug | 4 |
The same data as CSV
source,target,value
Search,Success (2xx),370
Search,Client error (4xx),22
Search,Server error (5xx),8
Checkout,Success (2xx),135
Checkout,Client error (4xx),8
Checkout,Server error (5xx),7
Login,Success (2xx),175
Login,Client error (4xx),22
Login,Server error (5xx),3
Catalogue,Success (2xx),240
Catalogue,Client error (4xx),8
Catalogue,Server error (5xx),2
Client error (4xx),Invalid input,25
Client error (4xx),Expired token,20
Client error (4xx),Not found,10
Client error (4xx),Rate limited,5
Server error (5xx),Timeout,10
Server error (5xx),Dependency failure,6
Server error (5xx),Bug,4How it works
Export a window of request logs
Take one hour, day or week, with the endpoint and status code for each request.
Group endpoints and status codes
Keep the four to six busiest endpoints, and group the rest as Other. Group status codes into classes.
Add the cause of each error
Use the error code or message your service returns. Group causes into five to seven labels.
Check the balance
Each error class must leave as many requests as entered. Successes end at the second column.
Frequently asked questions
Should redirects (3xx) be shown?
Only if they matter to your question. Otherwise count them as success, or leave them out and say so in the data note.
Can I use this for real-time monitoring?
No. It is a picture of a fixed window. A monitoring tool is better for live rates; the diagram is for explaining where failures come from.
Edit this API Sankey
Open the example as your own chart and enter your request counts.