> ## Documentation Index
> Fetch the complete documentation index at: https://docs.decibel.trade/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Handling

> Common API errors and how to handle them

The REST API uses standard HTTP status codes and returns JSON error objects with detail about what went wrong.

## Error Response Format

All error responses have the same shape:

```json theme={null}
{
  "status": "failed",
  "message": "Human-readable error description"
}
```

The `status` field is one of:

| Status     | Meaning                           |
| ---------- | --------------------------------- |
| `failed`   | Generic error                     |
| `timeout`  | Query execution timed out         |
| `notFound` | Requested resource does not exist |

### Examples

**Bad request (400):**

```json theme={null}
{
  "status": "failed",
  "message": "Bad Request: missing required parameter 'market'"
}
```

**Not found (404):**

```json theme={null}
{
  "status": "notFound",
  "message": "Market not found"
}
```

**Timeout (504):**

```json theme={null}
{
  "status": "timeout",
  "message": "Query execution timed out. Please try a more specific query or reduce the time range."
}
```

**Internal error (500):**

```json theme={null}
{
  "status": "failed",
  "message": "Service temporarily unavailable. Please try again later."
}
```

## HTTP Status Codes

| Status | Meaning                                       |
| ------ | --------------------------------------------- |
| 200    | Success                                       |
| 400    | Bad Request: Invalid parameters               |
| 401    | Unauthorized: Missing or invalid token        |
| 403    | Forbidden: Token lacks required scope         |
| 404    | Not Found: Resource doesn't exist             |
| 429    | Too Many Requests: Rate limit exceeded        |
| 500    | Server Error: Something went wrong on our end |
| 504    | Gateway Timeout: Query took too long          |

### Best Practices

1. Implement exponential backoff for 500/504 errors
2. Cache responses where appropriate
3. Batch requests when possible
4. Use WebSocket for real-time data instead of polling

## SDK Error Handling

See [TypeScript SDK Error Responses](/typescript-sdk/error-responses) for SDK-specific error handling.

## Related

<CardGroup cols={2}>
  <Card title="Authentication" href="/api-reference/rest/authentication">
    How to get and use bearer tokens
  </Card>

  <Card title="REST Overview" href="/api-reference/rest/overview">
    API basics and available endpoints
  </Card>
</CardGroup>