Error Codes

All APIs return JSON errors on non-2xx responses. Shape varies slightly by host but follows the same patterns.

Common response shape

{
  "error": "missing_wallet",
  "message": "wallet query parameter is required"
}

Agent and credit APIs may also include code instead of or alongside error.

Status	Meaning	Typical cause
400	Bad request	Missing or invalid parameters
401	Unauthorized	Missing or invalid fairkey
402	Payment required	No fairkey on a paid endpoint
404	Not found	Unknown route or wallet profile
429	Rate limited	Plan quota or burst limit exceeded
502	Upstream error	Scoring engine temporarily unavailable

Code	Endpoint	Fix
`missing_wallet`	Most	Pass `wallet` query param
`invalid_wallet`	Most	Use valid base58 Solana address (32-44 chars)
`invalid_preset`	`/v1/score/ai`	Use a documented preset name
`weights_must_sum_to_1`	`/v1/score/ai`	Custom weights must sum to 1.0 (+/- 0.02)
`missing_weights`	`POST /v1/score/ai`	Include weights body for custom scoring
`too_many_wallets`	`/v1/score/batch`	Max 25 wallets per batch request

Code	Endpoint	Fix
`missing_wallet`	`/score`, shortcuts	Pass `wallet` query param
`invalid_wallet`	`/score`, shortcuts	Valid Solana address

Code	Meaning
`daily_limit_exceeded`	Partner key daily quota reached
`rate_limit_exceeded`	Burst rate limit hit

Retry with exponential backoff. See Rate Limiting for plan tiers.

try {
  const score = await client.score("WALLET");
} catch (err: any) {
  console.error(err.status, err.code ?? err.message);
}

Host	Auth header	Docs
`api.fairscale.xyz`	`fairkey`	Score
`agent-api.fairscale.xyz`	`fairkey` or `X-Api-Key`	Agent Score, Credit