opensource/developer-roadmap
3
0
Fork 0
mirror of https://github.com/kamranahmedse/developer-roadmap.git synced 2026-10-24 01:08:07 +08:00
Code Issues Packages Projects Releases Wiki Activity

Improve "Error Handling / Retries" in API Design roadmap (#10437)

Browse Source 
Rewrite the topic copy to reflect current practice: retry only transient
failures (timeouts, 429, 502-504), cap retries, use exponential backoff
with jitter, respect Retry-After, and retry only idempotent requests.
The old copy suggested retrying until a request succeeds, which can cause
retry storms.

Add three resources on backoff, jitter and Retry-After. No other topic in
the API Design, Backend or AI Engineer roadmaps covers these yet.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Sree Vardhan V
2026-10-13 10:30:18 +02:00
committed by GitHub
co-authored by Claude Opus 5.5
parent f1e977f376
commit ac8ddd654c
1 changed files with 4 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
roadmaps/api-design/content/error-handling--retries@XD1vDtrRQFbLyKJaD1AlA.md
+4 -1
View File
@@ -1,8 +1,11 @@
# Error Handling / Retries
When creating effective API designs, addressing Error Handling and Retries forms an essential facet. This is primarily due to the fact that APIs aren't always error-free and instances of network hiccups or input inaccuracies from users can occur. Without robust error handling, such occurrences can easily lead to catastrophic application failure or unsatisfactory user experiences. Error handling can refer to validating inputs, managing exceptions, and returning appropriate error message or status codes to the user. Meanwhile, the concept of retries comes into play to ensure maximum request success amidst transient failures. Through correctly implemented retries, an API can repeatedly attempt to execute a request until it is successful, thus ensuring seamless operation.
Error handling and retries decide how an API and its clients behave when something goes wrong. On the server, good error handling means validating input early, returning the correct HTTP status code (`4xx` for client mistakes, `5xx` for server faults) and a consistent, machine-readable error body, such as the Problem Details format, so clients can react programmatically. On the client, only transient failures like timeouts, `429 Too Many Requests`, `502`, `503` and `504` are worth retrying, while errors such as `400` or `404` will fail again. Retries should be capped, spaced out with exponential backoff and jitter so many clients don't retry at the same moment, respect the `Retry-After` header when the server sends one, and be used only for idempotent requests (or ones protected by an idempotency key) so a repeated call can't cause duplicate side effects.
Visit the following resources to learn more:
- [@article@Timeouts, retries, and backoff with jitter - AWS Builders' Library](https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/)
- [@article@Exponential Backoff and Jitter - AWS Architecture Blog](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/)
- [@article@Retry-After header - MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Retry-After)
- [@article@How To Improve Your Backend By Adding Retries to Your API Calls](https://hackernoon.com/how-to-improve-your-backend-by-adding-retries-to-your-api-calls-83r3udx)
- [@video@How to Make Resilient Web Applications with Retries](https://www.youtube.com/watch?v=Gly94hp3Eec)