Error Reference

All GoRover API errors return a structured response:

{
  "error": {
    "code": "SCOUT_UNAUTHORIZED",
    "message": "Scout key is invalid or not registered.",
    "action": "Generate a new Scout key from your Rover dashboard."
  }
}

Authentication

• SCOUT_UNAUTHORIZED (401)
  Scout key missing or invalid.
  Action: regenerate Scout key in dashboard.
• SCOUT_SIGNATURE_INVALID (401)
  Beacon HMAC signature mismatch.
  Action: verify Swarm signing secret in config.
• SCOUT_DORMANT (403)
  Scout inactive for too long.
  Action: send fresh Beacon to reactivate.
• ADMIN_FORBIDDEN (403)
  Wallet is not admin wallet.
  Action: use wallet set in ADMIN_WALLET.
• PAYMENT_REQUIRED (402)
  x402 payment required.
  Action: complete USDC payment and retry.

Rate Limits

• RATE_LIMIT_IP (429)
  Public API request limit exceeded.
  Action: wait 60 seconds, then retry.
• RATE_LIMIT_BEACON (429)
  Beacon frequency too high.
  Action: lower Beacon frequency.
• FREE_TIER_EXCEEDED (429)
  Free Radar quota exhausted.
  Action: wait daily reset or upgrade tier.

Validation

• STAKE_UNVERIFIABLE (422)
  Transaction hash not verifiable.
  Action: verify tx hash on Solana mainnet.
• PNL_SUSPICIOUS (422)
  PnL outlier rejected.
  Action: re-check source data.
• BEACON_EXPIRED (422)
  Beacon data too old.
  Action: send recent stake data only.
• SCHEMA_INVALID (422)
  Request body format mismatch.
  Action: follow API schema exactly.

Server Side

• SWARM_UNAVAILABLE (503)
  Swarm temporarily unavailable.
  Action: check status.gorover.xyz, retry later.
• RADAR_UNAVAILABLE (503)
  Radar service paused or degraded.
  Action: check status page and retry.
• DB_UNAVAILABLE (503)
  Database unavailable.
  Action: retry after service recovers.

Troubleshooting

I keep getting 5xx responses

• Check status.gorover.xyz first.
• Retry with exponential backoff.
• Keep request payload unchanged during retries.

Next Steps

• Beacon