Skip to main content

​
Error response format

All errors follow the same structure: 
{
  "error": {
    "code": "error_code",
    "message": "Human-readable description."
  }
}
Some errors include additional fields (e.g., signup_url, can_assess).

​
Error codes

HTTP StatusCodeDescription
400bad_requestInvalid request parameters
400invalid_addressAddress is not a valid EVM address
401signup_requiredMissing or invalid API key
402payment_requiredEndpoint requires a paid plan
403account_cancelledAccount has been cancelled
404unknown_addressAddress not yet indexed (includes can_assess: true)
429rate_limitedRate limit exceeded
500internal_errorUnexpected server error

​
Common errors

​
No API key (401)

{
  "error": {
    "code": "signup_required",
    "message": "Sign up for a free account to use the AgentScore API.",
    "signup_url": "https://agentscore.sh/sign-up"
  }
}

{
  "error": {
    "code": "payment_required",
    "message": "This endpoint requires a paid plan ($49/mo). Upgrade at https://agentscore.sh/pricing"
  }
}

​
Account cancelled (403)

{
  "error": {
    "code": "account_cancelled",
    "message": "Your account has been cancelled."
  }
}

​
Unknown address (404)

{
  "error": {
    "code": "unknown_address",
    "message": "Address not yet indexed.",
    "can_assess": true
  }
}
Use POST /v1/assess to score unknown addresses on-the-fly.

​
Rate limited (429)

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Try again in 1 second."
  }
}
The Retry-After header indicates how many seconds to wait.