Developers

Errors and rate limits

HiveBase returns agent-readable errors for missing scopes, tool failures, rate limits, and dispatch-budget caps.

Missing scope

403 responses should tell the caller which scope is missing so agents and developers can recover.

{
  "error": {
    "code": "forbidden",
    "message": "Missing required scope: task:write"
  }
}

MCP tool errors

MCP tools/call failures use JSON-RPC error envelopes. Dispatch budget failures use tool errors instead of raw HTTP 429s.

{
  "jsonrpc": "2.0",
  "id": "req_123",
  "error": {
    "code": -32003,
    "message": "Dispatch budget exceeded for this token."
  }
}

Rate-limit inspection

Call auth.whoami or auth.activity.recent to inspect token limits, calls remaining, recent usage, and WU balance.

auth.whoami({})