> ## 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.

# Errors

> Error responses, status codes, and troubleshooting

## Error Format

All error responses return JSON with an `error` string:

```json theme={null}
{ "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):

```json theme={null}
{ "error": "Authorization header missing or malformed" }
```

* Invalid API key or unavailable plan access (403):

```json theme={null}
{ "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:

```json theme={null}
{ "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)

```json theme={null}
{ "error": "Rate limit exceeded", "retryAfter": 42 }
```

See the `Retry-After` header for how many seconds to wait.

## Not Found (404)

```json theme={null}
{ "error": "Not Found", "path": "/v1/invalid/route", "method": "GET" }
```