Concepts
Errors and retries
Separate request problems from temporary failures and retry only when it is safe.
On this page
Error envelope
Every public error uses the same JSON shape. requestId also appears in X-Request-Id.
{"error": {"code": "INVALID_REQUEST","message": "The request body is invalid.","requestId": "117aee90-61f5-4dc0-aac9-d20d40efcaa4","status": 400}}
When to retry
| Response | Retry? | Action |
|---|---|---|
| 400, 401, 403, 404, 410, 413, 422 | No | Correct the request or workspace state. |
| 409 idempotency conflict | No | Use the original payload or a new key. |
| 409 attachment not ready | Later | Complete validation before sending. |
| 429 | Later | Wait for the workspace limit window. |
| 500 or 503 | Yes | Use exponential backoff and the same idempotency key. |
Useful debugging context
- HTTP status and stable error code.
- The X-Request-Id response header.
- The message or attachment ID.
- The idempotency key without the API key.
- The time and operation that failed.