Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.shoal.xyz/llms.txt

Use this file to discover all available pages before exploring further.

​
Error Format

All error responses return JSON with an error string: 
{ "error": "Authorization header missing or malformed" }

​
Common Status Codes

  • 400 Bad Request: missing or invalid parameter
  • 401 Unauthorized: missing or malformed Authorization header
  • 403 Forbidden: invalid API key or endpoint unavailable on the current plan
  • 404 Not Found: invalid endpoint path
  • 429 Too Many Requests: rate limit exceeded
  • 500 Internal Server Error: unexpected server error

​
Authentication Errors

  • Missing or malformed header (401):
{ "error": "Authorization header missing or malformed" }
  • Invalid API key or unavailable plan access (403):
{ "error": "Invalid API key" }
Plan-gated endpoints may also return 403 with a message indicating that the endpoint is only available on higher-tier plans.

​
Missing since Parameter (400)

The /v1/radar/all and /v1/signal/all endpoints require the since query parameter: 
{ "error": "The 'since' parameter is required. Use an ISO 8601 timestamp (e.g. 2026-02-01T00:00:00Z)." }
This also applies if since is present but not a valid date (e.g. since=garbage).

​
Rate Limit Exceeded (429)

{ "error": "Rate limit exceeded", "retryAfter": 42 }
See the Retry-After header for how many seconds to wait.

​
Not Found (404)

{ "error": "Not Found", "path": "/v1/invalid/route", "method": "GET" }