Error Format

All errors return a consistent JSON shape:

{
  "error": "Human readable message",
  "code": "VALIDATION_ERROR",
  "requestId": "optional-uuid-for-prepare-failures"
}

Error codes

Code	Description
VALIDATION_ERROR	Invalid request body or parameters, including unknown or malformed chainId. REST prepare and simulation failures also use this code
NOT_FOUND	Resource does not exist
UPSTREAM_ERROR	RPC or subgraph failure
RATE_LIMITED	Tier rate limit exceeded
PREPARE_FAILURE	MCP prepare-layer failure (may include requestId). Not returned by REST
UNAUTHORIZED	Invalid or revoked developer API key (HTTP 401). Does not fall back to the free tier
FORBIDDEN	Credential is not allowed for this request (HTTP 403). Includes MCP rejecting Builder cts_… sessions and :me routes without Builder
AUTH_RATE_LIMITED	Too many failed auth attempts from this IP (HTTP 429)
API_DISABLED	REST is temporarily unavailable (HTTP 503)

Unsupported REST ?chainId= (for example 1 or not-a-chain) returns 400 with code: "VALIDATION_ERROR" and a message such as Unsupported chainId 1. See Chain selection.

Validation errors

Write endpoints may include an issues array with field-level details:

{
  "error": "Validation failed",
  "code": "VALIDATION_ERROR",
  "issues": [
    { "path": "from", "message": "Invalid address" }
  ]
}

Prepare failures

Include requestId when reporting prepare issues.

REST prepare and simulation failures return code: "VALIDATION_ERROR". MCP prepare-layer failures return code: "PREPARE_FAILURE".

Simulation failures on MCP throw before the tool result is returned.