Retries & errors
Handle retries, request limits and uncertain outcomes without duplicate actions.
Repeat safely
All write methods require Idempotency-Key: 8–128 characters containing letters, numbers, dots, underscores, colons or hyphens. Reusing the same key with a changed request returns 409. Completed operations return the stored result and Idempotency-Replayed:true.
If execution is still running or its outcome is uncertain, inspect Organization settings → Developers → Activity before starting a new operation. A failed network connection does not prove that a message or financial action failed.
Status codes
| Status | Meaning | Next action |
|---|---|---|
| 400 | Invalid request | Fix the named field. |
| 401 | Invalid, expired or revoked token | Check access; create a replacement when needed. |
| 403 | Missing scope or permission | Ask the organization owner to grant the appropriate access. |
| 404 | Resource not found or inaccessible | Check its ID and organization. |
| 409 | Conflict, in progress or uncertain | Inspect the operation; keep the same key. |
| 410 | Event cursor expired | Reconcile current resources and use the restart cursor. |
| 422 | Business or moderation validation | Correct the rejected operation. |
| 429 | Request limit reached | Honor Retry-After when supplied; use backoff. |
| 503 | Unavailable | Keep the key and check operation history before retrying. |
Request tracing and limits
Responses include X-Request-Id; writes also include X-Operation-Id. Keep those IDs when reporting a problem. Limits are 120 requests/token/minute and 480/organization/minute, with 4 simultaneous requests/token and 8/organization.