Error Classification

​

Overview

​

Error Categories

1. Retriability: Should the request failover to another provider?
2. Circuit Breaker Penalty: Should this error count against the provider’s failure threshold?

​

Retriable Categories

• Provider rate limiting or quota exceeded
• Temporary backpressure (will recover)
• Retriable: Yes (try different provider)
• Breaker Penalty: No (not a failure, just temporary constraint)
• Examples: “rate limit exceeded”, “too many requests”, “quota exceeded”

• Network/connectivity issues
• Transient failures (TCP errors, timeouts)
• Retriable: Yes
• Breaker Penalty: Yes
• Examples: Connection refused, DNS failure, socket timeout

• Provider-side server errors (5xx, provider crashes)
• Retriable: Yes
• Breaker Penalty: Yes
• Examples: “please retry”, “temporary internal error”, HTTP 500-599

• Provider lacks capability for this request
• Retriable: Yes (try provider with different capabilities)
• Breaker Penalty: No (permanent constraint, not transient failure)
• Examples: “block range too large”, “archive node required”, “tracing not enabled”

• Method not supported by this provider
• Retriable: Yes (try provider that supports the method)
• Breaker Penalty: Yes
• Examples: JSON-RPC -32601, “method unavailable”

• Provider internal error (JSON-RPC -32603)
• Retriable: Yes
• Breaker Penalty: Yes

• Authentication/authorization failure
• Retriable: Yes (credentials may work on different provider)
• Breaker Penalty: Yes
• Examples: “unauthorized”, “api key”, “forbidden”

• Chain-level error (e.g., unsupported chain)
• Retriable: Yes
• Breaker Penalty: Yes
• Examples: EIP-1193 4900, “unsupported chain”

​

Non-Retriable Categories

• Malformed JSON-RPC request
• Retriable: No (client error, won’t succeed elsewhere)
• Breaker Penalty: No (not provider’s fault)
• Examples: JSON-RPC -32600

• Invalid method parameters
• Retriable: No
• Breaker Penalty: No
• Examples: JSON-RPC -32602, “invalid address format”

• JSON parsing failure
• Retriable: No
• Breaker Penalty: No
• Examples: JSON-RPC -32700

• User rejected transaction (EIP-1193)
• Retriable: No
• Breaker Penalty: No
• Examples: EIP-1193 4001 (user rejected)

• Generic client error (4xx)
• Retriable: No
• Breaker Penalty: No
• Examples: HTTP 400, 403, 404

​

Special Categories

• Request timeout
• Retriable: Yes
• Breaker Penalty: Yes

• Infrastructure-level provider unavailability (no channels, pool errors)
• Retriable: Yes
• Breaker Penalty: Yes

• Unclassified error (fallback category)
• Retriable: No (conservative default)
• Breaker Penalty: Yes

​

Classification Strategy

1. Message-based patterns (highest priority)
2. Code-based classification (fallback)

​

Message-Based Classification

@rate_limit_patterns [
  "rate limit",
  "too many requests",
  "throttled",
  "quota exceeded",
  "capacity exceeded",
  "compute units",
  "timeout on the free tier"
]

@capability_violation_patterns [
  "block range exceeded",
  "archive node required",
  "tracing not enabled",
  "free tier",
  "upgrade your plan",
  "missing trie node",
  "result set too large"
]

@auth_patterns [
  "unauthorized",
  "api key",
  "forbidden",
  "access denied"
]

1. Rate limits (checked first)
2. Auth errors
3. Transient server errors (“please retry”)
4. Result size violations (provider-specific capabilities)
5. Other capability violations

categorize(-32000, "block range too large")
# => :capability_violation (message match)

categorize(-32000, "unknown error")
# => :server_error (code fallback: -32000 is server error range)

​

Code-Based Classification

@provider_specific_codes %{
  30 => :rate_limit,           # DRPC: "timeout on the free tier"
  35 => :capability_violation, # DRPC: capability constraint
  -32046 => :rate_limit,       # PublicNode: rate limit
  -32701 => :capability_violation  # 1RPC: range limit
}

​

API Reference

​

categorize/2

@spec categorize(integer(), String.t() | nil) :: atom()

ErrorClassification.categorize(-32000, "block range too large")
# => :capability_violation

ErrorClassification.categorize(-32602, nil)
# => :invalid_params

ErrorClassification.categorize(429, "rate limit exceeded")
# => :rate_limit

​

retriable?/2

@spec retriable?(integer(), String.t() | nil) :: boolean()

ErrorClassification.retriable?(-32000, "temporary internal error")
# => true

ErrorClassification.retriable?(-32602, "invalid address")
# => false

​

retriable_for_category?/1

@spec retriable_for_category?(atom()) :: boolean()

ErrorClassification.retriable_for_category?(:rate_limit)
# => true

ErrorClassification.retriable_for_category?(:invalid_params)
# => false

ErrorClassification.retriable_for_category?(:capability_violation)
# => true  # Try a provider with different capabilities

​

breaker_penalty?/1

@spec breaker_penalty?(atom()) :: boolean()

ErrorClassification.breaker_penalty?(:server_error)
# => true

ErrorClassification.breaker_penalty?(:capability_violation)
# => false  # Permanent constraint, not transient failure

ErrorClassification.breaker_penalty?(:rate_limit)
# => false  # Temporary backpressure with known recovery

​

Integration with Circuit Breakers

​

Classification Flow

# 1. Classify error
category = ErrorClassification.categorize(code, message)

# 2. Derive behavior
error_info = %{
  category: category,
  retriable?: ErrorClassification.retriable_for_category?(category),
  breaker_penalty?: ErrorClassification.breaker_penalty?(category)
}

# 3. Apply circuit breaker logic
if error_info.breaker_penalty? do
  CircuitBreaker.record_failure(provider_id, transport)
end

# 4. Trigger failover if retriable
if error_info.retriable? do
  Selection.select_next_provider(exclude: [failed_provider_id])
end

​

Why No Penalty for Capability Violations?

• A provider without archival data will never have archival data
• A free tier provider will always have block range limits
• Tracing unavailability is a configuration decision, not a health issue

​

Why No Penalty for Rate Limits?

• Rate limits reset on a predictable schedule (per second, per hour)
• RateLimitState tiering handles backpressure without circuit breakers
• Provider is healthy, just temporarily at capacity

​

Provider Capability Overrides

providers:
  - id: "ethereum_drpc"
    url: "https://eth.drpc.org"
    capabilities:
      error_rules:
        - code: 30
          message_contains: "timeout on the free tier"
          category: rate_limit
        - code: 35
          category: capability_violation
        - code: 19
          message_contains: "please retry"
          category: server_error

1. Provider-specific rules (top-to-bottom, first match wins)
2. Global ErrorClassification (message patterns, then code ranges)

case Capabilities.classify_error(code, message, capabilities) do
  {:ok, category} -> category  # Provider override matched
  :default -> ErrorClassification.categorize(code, message)  # Global classification
end

​

Common Error Patterns

​

Rate Limit Errors

{"code": 30, "message": "timeout on the free tier, please consider ordering a dedicated full node..."}

{"code": -32005, "message": "rate limit exceeded"}

​

Capability Violations

{"code": -32000, "message": "block range exceeded, max is 1k blocks"}

{"code": -32000, "message": "missing trie node (archive node required)"}

{"code": -32000, "message": "query returned more than 10000 results"}

​

Transient Server Errors

{"code": 19, "message": "Temporary internal error. Please retry"}

{"code": -32000, "message": "service temporarily unavailable"}

​

Invalid Client Requests

{"code": -32602, "message": "invalid address format"}

{"code": -32601, "message": "the method eth_traceBlock does not exist"}

​

Telemetry Integration

[:lasso, :circuit_breaker, :failure]
# Metadata: chain, provider_id, transport, error_category, circuit_state

:telemetry.execute(
  [:lasso, :circuit_breaker, :failure],
  %{count: 1},
  %{
    chain: "ethereum",
    provider_id: "alchemy",
    transport: :http,
    error_category: :network_error,  # From ErrorClassification
    circuit_state: :closed
  }
)

• Distinguish transient failures from capability constraints
• Track rate limit incidents separately from server errors
• Identify provider-specific error patterns

​

Best Practices

​

For Provider Configuration

1. Add custom error_rules: Provider error codes/messages vary widely
2. Test error scenarios: Verify classification matches expected behavior
3. Document edge cases: Note provider-specific quirks in YAML comments

​

For Monitoring

1. Alert on high breaker penalty errors: Server errors, network errors, timeouts
2. Track capability violations separately: May indicate client usage pattern mismatch
3. Monitor rate limit trends: May indicate need for tier upgrade or better load distribution

​

For Development

1. Test both code and message: Classification logic has two paths
2. Verify retriability: Failover behavior depends on correct classification
3. Check breaker penalty: Ensure transient failures penalize, constraints don’t

​

Related Documentation

• WebSocket Subscriptions - Failover triggers based on error classification
• Benchmarking - Error categories tracked in performance metrics
• Block Sync - Health probe error handling