Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.agentscore.sh/llms.txt

Use this file to discover all available pages before exploring further.

​
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_addressInvalid wallet address
400invalid_identityNeither address nor operator_token provided
400invalid_test_addressTest mode requires a reserved test address
401signup_requiredMissing or invalid API key
401unauthorizedMissing X-Poll-Secret header on session poll
401invalid_credentialOperator credential doesn’t exist (typo, never minted, fabricated). Permanent — the response body carries no auto-session because the agent likely has another valid token to try first.
401token_expiredOperator credential was valid but is now revoked or past its TTL (the API doesn’t disclose which). The 401 body carries an auto-minted verification session (verify_url + session_id + poll_secret) so the user can re-verify and the agent can poll for a fresh operator_token.
402payment_requiredEndpoint not enabled for this account
403account_cancelledAccount has been cancelled
404not_foundResource not found
404unknown_addressAddress not yet indexed (includes can_assess: true)
429rate_limitedRate limit exceeded (per-second)
429quota_exceededAccount quota exceeded
500internal_errorUnexpected server error
5xxapi_errorTransient infra failure on /v1/assess; body carries agent_instructions retry-with-backoff envelope

​
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"
  }
}

​
Endpoint not enabled for account (402)

{
  "error": {
    "code": "payment_required",
    "message": "This endpoint is not enabled for your account. See https://agentscore.sh/pricing"
  }
}

​
Account cancelled (403)

{
  "error": {
    "code": "account_cancelled",
    "message": "Account is 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 later."
  }
}
The Retry-After header indicates how many seconds to wait.

​
Quota exceeded (429)

{
  "error": {
    "code": "quota_exceeded",
    "message": "Account quota exceeded."
  }
}
quota_exceeded is a per-account cap — distinct from rate_limited (per-second sliding window). Don’t retry; the cap won’t lift through retry alone. Commerce SDKs can opt in to graceful degradation on this code via failOpen / fail_open — see compliance-gating › Fail-open behavior. When fail-open is off, the gate’s 503 response carries agent_instructions with action: "contact_merchant" (NOT retry_with_backoff), so agents surface the issue to the user instead of looping on a permanently-failing endpoint.

​
Retryable infra errors (api_error)

503 responses with error.code: "api_error" carry a structured agent_instructions envelope. The action discriminates the cause and tells the agent how to recover:

​
Transient 5xx / network timeout — retry_with_backoff

{
  "error": {
    "code": "api_error",
    "message": "Upstream service temporarily unavailable."
  },
  "agent_instructions": {
    "action": "retry_with_backoff",
    "steps": [
      "Wait 5-30 seconds before retrying",
      "Use exponential backoff if subsequent retries also fail",
      "If the error persists for over 5 minutes, surface the issue to the user"
    ],
    "user_message": "AgentScore is experiencing a transient issue. Retrying shortly."
  }
}

​
Merchant-side 429 — contact_merchant

{
  "error": {
    "code": "api_error",
    "message": "AgentScore is unreachable. This is transient — retry in a few seconds."
  },
  "agent_instructions": {
    "action": "contact_merchant",
    "steps": [
      "AgentScore identity verification is unavailable for this merchant. This is a merchant-side issue and is NOT recoverable via retry.",
      "Do not retry: the same 503 will be returned until the merchant resolves the issue on their side.",
      "Surface to the user with the merchant's support contact. The merchant (not the agent) needs to act."
    ],
    "user_message": "This merchant's identity verification is temporarily unavailable. Try again later, or contact the merchant directly."
  }
}
Agents must read agent_instructions.action before retrying. Do NOT loop on api_error blindly — when the action is contact_merchant, the same 503 will keep returning until the merchant resolves the issue on their side. The Node and Python commerce SDKs forward this envelope to buyers as part of the 503 response when failOpen is off (the default). When failOpen is on, the SDKs swallow the 5xx and pass the buyer through with degraded: true + infra_reason: "api_error" | "quota_exceeded" | "network_timeout" on the gate state — see compliance-gating › Fail-open behavior.