Guides
Errors & retries
Handle failures without duplicate messages.
Error body
JSON contains an error string; branch on HTTP status, not exact wording.
Example
{"error":"A valid Idempotency-Key is required"}Statuses
Creates normally return 201; inbox provisioning returns 202; other successes return 200.
| Status | Meaning / action |
|---|---|
| 400 | Invalid fields, cursor or idempotency key |
| 401 | Authenticate or replace expired/revoked key |
| 403 | Check scopes, role, workspace and eligibility |
| 404 | Missing/inaccessible resource or unsupported route |
| 409 | Conflict, plan limit or pending operation |
| 413 | Reduce payload size |
| 429 | Respect Retry-After and back off |
| 503 | Temporarily unavailable; reconcile writes before retry |
Rate limits
Account and edge limits apply. Backend 429 responses include Retry-After: 60. DNS checks have a ten-second guard. Use exponential backoff with jitter; a rate ceiling is not a delivery throughput guarantee.
Write recovery
For sends/inbox creation reuse the original idempotency key and payload. For other writes read current state after ambiguous failures. Receiving-route 503 can mean pending durable work. Do not retry every 4xx.