# Errors and retries

Interpret the stable error envelope and retry only when safe

Canonical: https://alef-bot.top/en/developers/guides/errors-and-retries

Updated: 2026-07-13

## Error envelope

Every public API error includes error.code, error.message, error.request_id and error.details.resolution_url. Rely on code rather than message

> **Stable resolution links.** Open resolution_url for focused remediation. Unknown codes link back to this guide

## Retry policy

- Do not retry expected 401, 403 or 422 errors without changing the request
- Retry 429 only after Retry-After or X-RateLimit-Reset with a small random delay
- Use bounded exponential backoff for network failures and temporary 5xx errors
- After an uncertain response to POST /uploads or POST /transcriptions, reuse the original Idempotency-Key

## Machine-readable sources

- [OpenAPI JSON](https://alef-bot.top/api/v1/openapi.json)

- [OpenAPI YAML](https://alef-bot.top/api/v1/openapi.yaml)

- [Arazzo workflow](https://alef-bot.top/api/v1/workflows/transcribe.arazzo.yaml)