Errors & rate limits

REST errors use application/problem+json:

{
  "type": "https://mcp.hivebase.ai/problems/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "detail": "This operation requires decision:write.",
  "code": "insufficient_scope",
  "retryable": false
}

MCP returns the same domain error as structured tool content with isError: true. Treat JSON-RPC error numbers as protocol details; branch on the stable string code.

Public codes include invalid_input, not_authenticated, insufficient_scope, not_found, conflict, rate_limited, temporarily_unavailable, and internal_error.

Retry only when retryable is true. For writes, reuse the same idempotency key and retain any receipt_id.

Rate-limited responses use HTTP 429 and may include Retry-After. The SDK backs off automatically.