Error Response Format

All errors are returned in a uniform JSON format:

{
  "code": "error_code",
  "message": "Human-readable error description",
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Field	Type	Description
code	string	error code
message	string	error description
request_id	string	Unique request trace ID -- provide this when contacting support

---

Error Code Reference

Client Errors (4xx)

HTTP Status	Code	Description	Resolution
400	invalid_request	Bad request format (empty body, invalid JSON, or malformed JSON-RPC)	Verify the request body is valid JSON-RPC 2.0
400	tx_method_required	Non-transaction method sent to /v1/tx	Use /v1/rpc for query requests
401	auth_required	Missing API Key	Add X-User-ID: <your-api-key> header
403	forbidden	Access denied	Verify your API Key is valid
403	feed_not_entitled	Current plan does not include Feed access	Upgrade to VIP1 or higher
429	rate_limited	Request rate exceeds quota	Read the Retry-After header and wait before retrying
429	feed_limit_exceeded	Feed connection limit reached	Close an existing Feed connection first

Server Errors (5xx)

HTTP Status	Code	Description	Resolution
500	internal_error	Internal server error	Retry later; contact support if it persists
502	upstream_error	Upstream Robinhood Chain node error	Retry later
503	queue_full	Transaction system busy (/v1/tx only)	Retry later
504	upstream_timeout	Upstream node response timed out	Retry later

---

Troubleshooting FAQ

Symptom	Possible Cause	Solution
All requests return 401	Missing X-User-ID header	Add X-User-ID: <your-api-key> to request headers
Frequent 429 responses	Request rate exceeds plan limit	Reduce request frequency, or upgrade to a higher plan
Feed connection returns 403	Free plan does not include Feed	Upgrade to VIP1 or VIP2
RPC returns 502	Upstream Robinhood Chain node temporarily unavailable	Wait and retry
RPC returns 504	Upstream node response timed out	Wait and retry, or check network conditions
Transaction returns 503	System busy	Wait and retry

When troubleshooting, always note the request_id from the response. Providing this ID when contacting support will significantly speed up diagnosis.