Errors

Errors return a non-2xx status and a JSON body:

{
  "error": {
    "code": "forbidden",
    "message": "API key is not scoped to hub \"aevon\""
  }
}

Branch on code, not on message — messages may change, codes won't.

Status	Code	Meaning
400	`missing_wallet`	A required `wallet` parameter was absent.
400	`invalid_json`	Request body was not valid JSON.
401	`unauthorized`	Missing or unknown `x-api-key`.
401	`bad_signature`	HMAC signature didn't verify.
401	`stale_timestamp`	`x-api-timestamp` outside the ±300s window.
403	`forbidden`	Key is valid but not scoped to this hub.
404	`not_found`	Hub or resource doesn't exist.
429	`rate_limited`	Too many requests — back off and retry.

Retrying safely¶

Reads are idempotent — retry freely with backoff. For the one write (/bits/earn), pass a stable ref so a retry after a network blip never double-awards. See Authentication.