Documentation version: Latest (v1)
Guide
Error handling and retries
Normalize API failures by status family, apply deterministic retry policy, and instrument alerts for production reliability.
Status code playbook
| Status | Family | Meaning | Common triggers | Recommended handling |
|---|---|---|---|---|
| 400 | Validation | Request payload or query is malformed. | Missing required fields, invalid email format, invalid JSON. | Do not retry blindly. Fix payload generation and validate before sending. |
| 401 | Auth | Credential is missing, malformed, or invalid. | No Authorization header, expired/revoked key. | Refresh or rotate credentials. Alert if this spikes in production. |
| 403 | Policy / scope | Caller is authenticated but not allowed. | Wrong key scope, sender not verified, IP allowlist blocked. | Check key scope and endpoint policy; do not retry until policy is fixed. |
| 404 | Not found | Resource id does not exist or is expired. | Unknown templateId, expired OTP session. | Treat as terminal; request a new resource/session. |
| 409 | Conflict | Request conflicts with server state. | Duplicate form submissions when duplicate mode is reject. | Surface clear UX and avoid automatic retries. |
| 423 | Locked/closed | Resource is disabled or limit-closed. | Inactive form, closed by response cap, monthly limit reached. | Show user-facing closed message and route to support channel. |
| 429 | Rate / quota | Request exceeded rate limit or quota window. | High burst sends, OTP retries, SMTP warmup daily cap. | Use exponential backoff + jitter and user-visible cooldown messaging. |
| 500 | Server | Unexpected internal error. | Unhandled runtime exception. | Retry with backoff and log correlation id/context. |
| 502 | Upstream | Upstream transport failure. | SMTP failure during direct OTP send. | Retry with fallback route and escalate if sustained. |
| 503 | Unavailable | Service is temporarily unavailable. | SMTP not configured, queue freeze mode, infra maintenance. | Retry later and alert operations team. |
Retry strategy reference
- Retry 429, 500, 502, and 503 with capped exponential backoff and jitter.
- Never retry 400, 401, 403, or 404 without changing request context.
- Record response status + body + endpoint + key id fingerprint for debugging.
- Surface user-friendly cooldown messages for OTP and form submit throttles.
Observability essentials
- Track per-endpoint success rate, p95 latency, and 4xx/5xx rates separately.
- Alert immediately on sudden 401/403 spikes (possible credential drift).
- Alert on 429 trends (capacity planning signal) and SMTP 503 spikes (transport outage).
- Store queue id/session id in your app logs for support correlation.