Error Codes

Overview

Aleatoric Data returns structured error responses across all four transport protocols. Each protocol uses its native error encoding while maintaining a consistent semantic mapping. This reference documents every error code, its meaning, and the recommended client action.

Error Taxonomy

All errors fall into one of five categories:

Category	Description	Client Action
Authentication	API key missing, invalid, expired, or revoked	Verify key, regenerate if needed
Authorization	Key valid but lacks required scope or tier	Upgrade tier or request scope
Validation	Malformed request, invalid parameters	Fix request and retry
Rate Limiting	Token bucket exhausted or concurrent limit hit	Back off and retry after indicated interval
Server	Internal error, upstream failure, maintenance	Retry with exponential backoff

---

HTTP Status Codes

All REST and JSON-RPC-over-HTTP responses use standard HTTP status codes:

Code	Name	Category	Description	Recommended Action
200	OK	—	Request succeeded	—
201	Created	—	Resource created (e.g., new subscription registered)	—
204	No Content	—	Success with no response body (e.g., DELETE)	—
400	Bad Request	Validation	Request body or query parameters are malformed	Check request format, validate against schema
401	Unauthorized	Authentication	API key is missing, invalid, or expired	Include a valid Authorization: Bearer <key> header
403	Forbidden	Authorization	API key is valid but lacks the required scope or tier	Upgrade your plan or contact support for scope adjustment
404	Not Found	Validation	Requested resource (coin, feed, endpoint) does not exist	Verify the resource identifier and endpoint path
405	Method Not Allowed	Validation	HTTP method not supported for this endpoint	Use the correct HTTP method (GET, POST, etc.)
408	Request Timeout	Server	Server did not receive the complete request in time	Retry; check network connectivity
413	Payload Too Large	Validation	Request body exceeds the 1 MB limit	Reduce payload size; split into multiple requests
422	Unprocessable Entity	Validation	Request is syntactically valid but semantically incorrect	Check parameter values, types, and ranges
429	Too Many Requests	Rate Limiting	Token bucket exhausted	Wait for Retry-After seconds, then retry
500	Internal Server Error	Server	Unexpected server-side failure	Retry with exponential backoff; report if persistent
502	Bad Gateway	Server	Upstream node or service unreachable	Try an alternate region; retry after 5s
503	Service Unavailable	Server	Maintenance or capacity overload	Check status page; retry after Retry-After
504	Gateway Timeout	Server	Upstream service did not respond within the deadline	Retry; if persistent, the upstream feed may be down

HTTP Error Response Body

All 4xx and 5xx responses return a consistent JSON structure:

{
  "error": "error_code_string",
  "message": "Human-readable description of the error.",
  "details": {
    "field": "coin",
    "reason": "Unknown coin identifier: INVALID"
  },
  "request_id": "req_a1b2c3d4e5f6",
  "timestamp": "2026-03-13T14:22:01.003Z"
}

The details object is present only for validation errors (400, 422) and contains field-level diagnostics. The request_id is included in every error response and should be referenced when contacting support.

---

JSON-RPC Error Codes

JSON-RPC 2.0 errors are returned in the error object of the response. Standard specification codes are in the range $[-32768, -32000]$. Aleatoric application-specific codes use the range $[-32099, -32000]$.

Standard JSON-RPC Codes

Code	Name	Description
-32700	Parse Error	Server received invalid JSON that could not be parsed
-32600	Invalid Request	JSON was valid but is not a conformant JSON-RPC 2.0 request (missing jsonrpc, method, or id fields)
-32601	Method Not Found	The requested method does not exist or is not available on this endpoint
-32602	Invalid Params	Method parameters are missing, have wrong types, or fail validation
-32603	Internal Error	Unspecified server-side error during method execution

Aleatoric Application Codes

Code	Name	Description
-32000	Rate Limit Exceeded	API key has exhausted its token bucket; includes retry_after in data
-32001	Authentication Failed	API key is missing or invalid
-32002	Tier Restricted	Method or parameter combination requires a higher tier
-32003	Coin Not Found	The specified coin identifier is not tracked by Aleatoric
-32004	Feed Unavailable	The requested feed is temporarily offline or not yet initialized
-32005	Subscription Limit	Maximum number of concurrent subscriptions reached for this key
-32006	Batch Too Large	Batch request exceeds the 100-call limit
-32007	Snapshot Too Large	Requested depth snapshot exceeds the maximum permitted size
-32008	Invalid Time Range	The start/end parameters define an invalid or excessively large time window
-32009	Upstream Timeout	An upstream data source did not respond within the deadline
-32010	Maintenance Mode	The service is in scheduled maintenance; retry after the window

JSON-RPC Error Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32003,
    "message": "Coin not found: INVALID",
    "data": {
      "param": "coin",
      "provided": "INVALID",
      "hint": "Use GET /v1/meta/coins for the list of supported identifiers"
    }
  }
}

Batch Error Handling

In a JSON-RPC batch, each call is processed independently. A batch response may contain a mix of successful results and errors:

[
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": { "mid": 87234.50, "spread_bps": 1.2 }
  },
  {
    "jsonrpc": "2.0",
    "id": 2,
    "error": {
      "code": -32003,
      "message": "Coin not found: SHIB"
    }
  }
]

---

gRPC Status Codes

gRPC responses use the standard google.rpc.Status code set. Additional context is provided via google.rpc.ErrorInfo detail messages.

Code	Status Name	Category	Description	Recommended Action
0	OK	—	Success	—
1	CANCELLED	—	Client cancelled the request	No action needed
2	UNKNOWN	Server	Unknown server error	Retry with backoff; report if persistent
3	INVALID_ARGUMENT	Validation	Request parameters are invalid	Fix parameters and retry
4	DEADLINE_EXCEEDED	Server	Server could not complete within the client’s deadline	Increase deadline or retry
5	NOT_FOUND	Validation	Requested coin, feed, or resource does not exist	Verify identifiers
7	PERMISSION_DENIED	Authorization	API key lacks required scope or tier for this RPC	Upgrade tier or request scope
8	RESOURCE_EXHAUSTED	Rate Limiting	Rate limit or concurrent connection limit exceeded	Back off per retry-after-ms metadata
10	ABORTED	Server	Operation aborted due to a conflict (e.g., concurrent snapshot)	Retry immediately
11	OUT_OF_RANGE	Validation	Request parameter outside valid range (e.g., depth > 1000)	Adjust parameters
12	UNIMPLEMENTED	Validation	Method exists in proto but is not yet available	Check documentation for availability
13	INTERNAL	Server	Internal server error	Retry with backoff
14	UNAVAILABLE	Server	Service temporarily unavailable (maintenance, overload)	Retry with backoff
16	UNAUTHENTICATED	Authentication	API key is missing or invalid	Include valid key in authorization metadata

gRPC Error Metadata

Rate-limited gRPC responses include trailing metadata:

Metadata Key	Description
retry-after-ms	Milliseconds until the next request will be accepted
x-ratelimit-remaining	Tokens remaining in the bucket
x-request-id	Request identifier for support reference

gRPC Stream Errors

For server-streaming and bidirectional RPCs, errors can occur at two points:

1. Connection time — the initial StreamOpen fails with a status code (e.g., UNAUTHENTICATED, RESOURCE_EXHAUSTED). No messages are delivered.
2. Mid-stream — the server terminates the stream with a status code after some messages have been delivered (e.g., INTERNAL, UNAVAILABLE). The client should reconnect with backoff.

---

Unified Stream (SSE) Error Events

SSE connections deliver errors as typed events on the open connection. After emitting an error event, the server may either keep the connection open (recoverable errors) or close it (terminal errors).

Error Event Format

event: error
data: {"code": "error_code", "message": "Human-readable description", "request_id": "req_abc123", "terminal": true}

The terminal field indicates whether the connection will be closed after this error.

SSE Error Codes

Code	Terminal	Category	Description	Recommended Action
auth_failed	Yes	Authentication	API key is missing, invalid, or expired	Reconnect with a valid key
auth_expired	Yes	Authentication	API key was valid at connect time but has since been revoked	Obtain a new key and reconnect
rate_limit	Yes	Rate Limiting	Concurrent stream limit exceeded for this tier	Close other streams or upgrade tier, then reconnect
tier_restricted	Yes	Authorization	Requested event type is not available on the current tier	Upgrade tier or remove the restricted type filter
coin_not_found	No	Validation	A requested coin identifier is not recognized	The stream continues for valid coins; fix the identifier
feed_stale	No	Server	A data source has not produced events for > 60 seconds	Monitor; the feed will auto-recover when data resumes
upstream_lag	No	Server	Data delivery is delayed due to upstream backpressure	Events are buffered; expect elevated latency
internal	Yes	Server	Unrecoverable server error	Reconnect with exponential backoff
maintenance	Yes	Server	Planned maintenance shutdown	Reconnect after the maintenance window
reconnect	Yes	Server	Server requests client reconnection (e.g., rebalancing)	Reconnect immediately

SSE Reconnection Protocol

When a terminal error is received:

1. Close the current connection.
2. Wait for the duration specified in the retry field (if present in the SSE stream), or use a default of 1 second.
3. Apply exponential backoff with jitter: wait $\min(2^n + \text{jitter},\; 30)$ seconds on the $n$-th consecutive failure.
4. Reconnect with the Last-Event-ID header set to the last received event ID to resume from the correct position.

---

WebSocket Close Codes

WebSocket connections use standard RFC 6455 close codes (1000—1015) and Aleatoric-specific application codes (4000—4099).

Standard Close Codes

Code	Name	Description
1000	Normal Closure	Clean shutdown initiated by either side
1001	Going Away	Server is shutting down or client is navigating away
1002	Protocol Error	WebSocket protocol violation
1003	Unsupported Data	Received a data type the endpoint cannot process
1006	Abnormal Closure	Connection lost without a close frame (network failure)
1008	Policy Violation	Message violates server policy (e.g., oversized frame)
1009	Message Too Big	Frame exceeds the 4 MB limit
1011	Internal Error	Server encountered an unexpected error
1013	Try Again Later	Server is overloaded; client should reconnect after backoff

Aleatoric Application Close Codes

Code	Name	Category	Description	Recommended Action
4001	Invalid API Key	Authentication	The provided API key is not valid	Verify key and reconnect
4002	Key Expired	Authentication	API key has expired since connection was established	Obtain a new key and reconnect
4003	Tier Not Authorized	Authorization	Current tier does not include WebSocket (Disk-Sync) access	Upgrade to Quant tier
4004	Coin Not Supported	Validation	Requested coin is not available for WebSocket sync	Check supported coins and reconnect
4005	Invalid Subscription	Validation	Subscription message is malformed	Fix the message format and reconnect
4006	Subscription Limit	Rate Limiting	Maximum subscription count exceeded for this connection	Reduce subscriptions or open additional connections
4007	Heartbeat Timeout	Server	Client did not respond to ping within 30 seconds	Ensure pong handler is implemented; reconnect
4008	Duplicate Connection	Rate Limiting	Another connection for this API key already exists	Close existing connection first
4009	Upstream Failure	Server	Upstream data source is unreachable	Reconnect with backoff
4029	Rate Limit Exceeded	Rate Limiting	Message send rate exceeds permitted throughput	Reduce message frequency; reconnect with backoff
4050	Maintenance	Server	Planned maintenance shutdown	Reconnect after the maintenance window

WebSocket Close Frame Payload

Application close codes (4000-4099) include a UTF-8 reason string in the close frame payload:

Close frame: code=4003, reason="Tier not authorized for Disk-Sync. Upgrade to Quant."

---

Cross-Protocol Error Mapping

The following table maps equivalent errors across all four protocols for common failure scenarios:

Scenario	HTTP	JSON-RPC	gRPC	SSE	WebSocket
Invalid API key	401	-32001	UNAUTHENTICATED (16)	auth_failed	4001
Tier insufficient	403	-32002	PERMISSION_DENIED (7)	tier_restricted	4003
Bad parameters	400	-32602	INVALID_ARGUMENT (3)	coin_not_found	4005
Coin not found	404	-32003	NOT_FOUND (5)	coin_not_found	4004
Rate limited	429	-32000	RESOURCE_EXHAUSTED (8)	rate_limit	4029
Server error	500	-32603	INTERNAL (13)	internal	1011
Maintenance	503	-32010	UNAVAILABLE (14)	maintenance	4050

---

Debugging Errors

Every error response includes a request_id (or equivalent identifier). When contacting support:

1. Include the request_id from the error response.
2. Note the protocol, endpoint, and approximate timestamp.
3. Include the full error payload (redacting your API key).

Error logs are retained for 30 days and can be queried by request_id for Enterprise clients with audit log access.