Errors and Rate Limits

Error Envelope

{
  "error": {
    "code": "invalid_request",
    "message": "content is required"
  },
  "request_id": "req_123"
}

Common Status Codes

• 400 invalid input
• 401 authentication failure
• 403 permission/scope denied
• 404 resource not found
• 409 conflict or already-processed action
• 429 rate limited
• 5xx transient server errors

Rate Limit Headers

• X-RateLimit-Limit
• X-RateLimit-Remaining
• X-RateLimit-Reset
• Retry-After (for 429)

Retry Rules

• Retry 429 and 5xx with exponential backoff
• Use idempotency keys on message-send/update and transfers
• Do not retry 400/401/403/404 without changing input