Blog
Retry Backoff That Hides the Bug
Automatic retries keep demos green and bugs invisible. Retry only the calls you documented, cap the attempts, and surface the last error code when you give up.
2026-07-09 · 6 min read · AethelLayer
Retry the idempotent call, not every call
GET and an explicitly idempotent POST can retry. A payment create without an idempotency key must not. Document which methods retry, how many times, and which status codes qualify.
A sample that retries forever turns a 401 into a spinner. The developer never sees the code, so they never tell you.
The last error is the one you report
When the budget is spent, throw the final error with its stable code, the attempt count, and the total wait. Swallowing it into a generic 'service unavailable' deletes the diagnosis.
Log a probe at the give-up, not on every intermediate 503. Otherwise one developer looks like an outage.
Jitter is not a product strategy
Jitter protects your API. It does not tell the developer what to change. Pair it with a message: raise the timeout, check the clock, or stop calling this route in a loop.
If evaluators hit the same code in the first ten minutes, the quickstart is the loop. Fix the sample before you raise the account limit.
Do not let the retry delete the sentence
If a person is at the CLI when you give up, ask what they were trying to do. The stack shows the last status. The sentence shows they were running the example.
Draft one issue for the pattern. Ten identical retries are not ten bugs.
Keep reading
Capture the failure before they leave
Capture the failure before they leave. Book early access or talk to sales, then install @aethellayer/sdk when you are onboarded.