> ## Documentation Index > Fetch the complete documentation index at: https://docs.agentscore.com/llms.txt > Use this file to discover all available pages before exploring further. # Errors > Error codes and response format. ## Error response format All errors follow the same structure: ```json theme={"dark"} { "error": { "code": "error_code", "message": "Human-readable description." } } ``` Some errors include additional fields (e.g., `signup_url`, `can_assess`). ## Error codes | HTTP Status | Code | Description | | ----------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 400 | `bad_request` | Invalid request parameters | | 400 | `invalid_address` | Invalid wallet address | | 400 | `invalid_identity` | Neither address nor operator\_token provided | | 400 | `invalid_test_address` | Test mode requires a reserved test address | | 401 | `signup_required` | Missing or invalid API key | | 401 | `unauthorized` | Missing X-Poll-Secret header on session poll | | 401 | `invalid_credential` | Operator 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. | | 401 | `token_expired` | Operator 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`. | | 402 | `payment_required` | Endpoint not enabled for this account | | 403 | `account_cancelled` | Account has been cancelled | | 404 | `not_found` | Resource not found | | 404 | `unknown_address` | Address not yet indexed (includes `can_assess: true`) | | 429 | `rate_limited` | Rate limit exceeded (per-second) | | 429 | `quota_exceeded` | Account quota exceeded | | 500 | `internal_error` | Unexpected server error | | 5xx | `api_error` | Transient infra failure on `/v1/assess`; body carries `agent_instructions` retry-with-backoff envelope | ## Common errors ### No API key (401) ```json theme={"dark"} { "error": { "code": "signup_required", "message": "Sign up for a free account to use the AgentScore API.", "signup_url": "https://www.agentscore.com/sign-up" } } ``` ### Endpoint not enabled for account (402) ```json theme={"dark"} { "error": { "code": "payment_required", "message": "This endpoint is not enabled for your account. See https://www.agentscore.com/pricing" } } ``` ### Account cancelled (403) ```json theme={"dark"} { "error": { "code": "account_cancelled", "message": "Account is cancelled" } } ``` ### Unknown address (404) ```json theme={"dark"} { "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) ```json theme={"dark"} { "error": { "code": "rate_limited", "message": "Rate limit exceeded. Try again later." } } ``` The `Retry-After` header indicates how many seconds to wait. ### Quota exceeded (429) ```json theme={"dark"} { "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](/compliance-gating#fail-open-behavior-opt-in). 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` ```json theme={"dark"} { "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` ```json theme={"dark"} { "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](/compliance-gating#fail-open-behavior-opt-in).