Graceful Degradation When an API Is Slow

Reference APIs go slow more often than they go down. The right pattern is not to wait forever; it is to degrade gracefully.

Three levels of degradation

1. Fresh data. Hit the API, wait up to 2 seconds.
2. Warm cache. Serve the last successful response with a stale=true marker. Useful for the next 10 minutes.
3. Cold fallback. A bundled, possibly older copy. Better than nothing, and clearly labeled as such.

Honest errors

If all three layers fail, return a structured error that says which level failed and what the user can do. "Try again in a minute" is better than a generic 500.

What not to do

• Block on the API for 30 seconds. The user has given up by then.
• Silently serve stale data without a marker. The next consumer in the chain will be confused.
• Return an empty answer. "I do not know" is sometimes right; "I have no idea and the API is fine" is rarely right.

YJTOON-specific

Our /static-data/ tree is the warm cache. The CDN serves it from the edge. A 200ms timeout to the API followed by a static fallback is the default for our own agents.