Error Handling & Troubleshooting

This service is at-least-once. Most operational issues show up as retries, duplicates, or auth failures.

Retry guidance

Retry on:

• 429 rate_limited
• 500 internal
• 503 unavailable
• network timeouts

Do not retry without changes on:

• 400 invalid_request
• 401 unauthorized
• 403 insufficient_scope

Backoff strategy

Use exponential backoff with jitter. Example schedule (milliseconds): 250, 500, 1000, 2000.

Idempotency expectations

• Publish should be retried with the same Idempotency-Key.
• Consumers should handle duplicate deliveries (same message.id).

Troubleshooting table

Symptom	Likely cause	Fix
401 unauthorized	Missing/invalid API key	Check Authorization header and environment selection
403 insufficient_scope	Key lacks required scope	Add messages:read/write/ack as needed
Messages reappear after processing	Consumer didn’t ack in time	Increase visibility timeout or ack earlier
Duplicate messages	Retries or consumer restarts	Make processing idempotent; dedupe by message.id
Frequent 429	Hitting rate limit	Reduce concurrency; add backoff; request higher quota

---

Next: Getting Started · Reference · Changelog · Support