Agent Tools

Errors

The Canon API uses standard HTTP status codes and returns structured JSON error responses.

Error Response Format

All errors return a JSON object with an error field. Validation errors additionally include a detail field:

{
  "error": "validation_error",
  "detail": "invalid asset: FAKECOIN"
}

Code	Meaning	Description
`200`	OK	Request succeeded
`400`	Bad Request	Invalid request parameters
`401`	Unauthorized	Missing or invalid API key
`404`	Not Found	Resource not found (e.g. no volatility data for requested backtest asset)
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Unexpected server error
`502`	Bad Gateway	Upstream data source unavailable
`503`	Service Unavailable	Service is starting up or circuit breaker is open
`504`	Gateway Timeout	Risk computation exceeded 10 second timeout

Missing or malformed Authorization header:

{
  "error": "missing or invalid Authorization header"
}

Invalid API key:

{
  "error": "invalid API key"
}

All validation errors return "error": "validation_error" with a specific detail message:

{
  "error": "validation_error",
  "detail": "leverage 100 exceeds maximum 50"
}

Detail pattern	Description
`invalid asset: {name}`	Asset not found or not available on Hyperliquid
`invalid wallet address: {addr}`	Wallet address is not a valid 42-character hex address
`size must be positive, got {n}`	Position size is not positive
`size {n} exceeds maximum allowed {max}`	Position size exceeds $100M maximum
`leverage {n} exceeds maximum {max}`	Requested leverage exceeds the asset's maximum
`asset {name} is delisted and cannot be traded`	Asset has been delisted
`asset {name} only supports isolated margin mode`	Asset only supports isolated margin; cross margin was requested

Batch-specific errors:

Error	Detail	Description
`batch_too_large`	`max 50 trades per batch`	Batch request exceeds 50 trades
`validation_error`	`trades array is empty`	Batch request contains no trades

Returned when Canon cannot fetch required data from the exchange.

{
  "error": "l2_book_fetch_failed"
}

{
  "error": "wallet_state_unavailable"
}

Returned when the service is still starting up and caches are not yet populated:

{
  "error": "service_starting"
}

Also returned when the upstream circuit breaker is open due to repeated failures.

Returned when risk computation exceeds the 10-second handler timeout:

{
  "error": "timeout",
  "detail": "risk computation exceeded 10s"
}