REFERENCE

Errors and retries

Handle API errors, rate limits, and delivery failures predictably.

Error format

Non-2xx responses include a JSON error description. Rate-limit responses also include standard rate-limit headers. Retry transient 429 and 5xx responses with exponential backoff and jitter.

{
  "error": "Monthly billable-message limit reached (5000 on pro plan). Upgrade to send more."
}

Retry without duplicate sends

Always attach an Idempotency-Key to a send before retrying a timeout, dropped MCP connection, or transient 5xx response. Keep the same key and payload across attempts. A replay response includes idempotentReplay: true; a changed payload with the same key returns 409.