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

# Error Codes

> Complete reference of API error codes, meanings, and resolution strategies.

## Overview

BlockDB API uses structured error envelopes with consistent codes, HTTP status, retry guidance, and links back to the docs. Use `hint`, `severity`, and `retryable` to decide whether to fix the request or retry later.

## Error Response Format

All error responses follow this structure (fields may vary by code):

<CodeGroup>
  ```json Error theme={null}
  {
    "error": {
      "code": "ERROR_CODE",
      "http_status": 400,
      "message": "Human-readable error message.",
      "hint": "Actionable guidance.",
      "severity": "error | warning | critical",
      "retryable": false,
      "details": {},
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```
</CodeGroup>

## Common Error Codes

### Authentication & Authorization

| Code                    | HTTP Status | Description                                | Resolution                                                                                     |
| ----------------------- | ----------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------- |
| `BAD_REQUEST`           | 400         | Invalid or missing parameters              | Fix fields listed in `details.invalid_parameters`; use ISO-8601 timestamps and valid chain IDs |
| `UNAUTHORIZED`          | 401         | Invalid or missing API key                 | Send `Authorization: Bearer <API_KEY>`; regenerate key if compromised                          |
| `FORBIDDEN`             | 403         | API key lacks permission for this endpoint | Upgrade plan or request access (`required_plan` in `details`)                                  |
| `NOT_FOUND`             | 404         | Resource does not exist                    | Verify endpoint path and parameters                                                            |
| `PAYLOAD_TOO_LARGE`     | 413         | Response would exceed size limits          | Lower `limit`, narrow block/time window, or reduce filters                                     |
| `RATE_LIMIT_EXCEEDED`   | 429         | Request rate exceeded                      | Apply client throttling/backoff and honor `retry_after_seconds`                                |
| `INTERNAL_SERVER_ERROR` | 500         | Unexpected server error                    | Safe to retry; include `incident_id` in support tickets                                        |

## Error Code Reference by Category

<AccordionGroup>
  <Accordion title="Authentication & Authorization">
    * `UNAUTHORIZED` (401)
    * `FORBIDDEN` (403)
  </Accordion>

  <Accordion title="Request Validation">
    * `BAD_REQUEST` (400)
    * `NOT_FOUND` (404)
  </Accordion>

  <Accordion title="Quota & Payload">
    * `RATE_LIMIT_EXCEEDED` (429)
    * `PAYLOAD_TOO_LARGE` (413)
  </Accordion>

  <Accordion title="Server Errors">
    * `INTERNAL_SERVER_ERROR` (500)
  </Accordion>
</AccordionGroup>

## See Also

* [Dataset index](/data-catalog/evm/dataset-index) — Dataset-scoped access and table names
* [Troubleshooting: API Error Codes](/troubleshooting/error-codes/api/home) - Detailed troubleshooting guide
* [Authorization](/api-reference/overview/authorization) - Authentication errors
* [Rate Limiting](/api-reference/overview/rate-limiting) - Rate limit handling
* [Raising a Support Ticket](/troubleshooting/raising-a-support-ticket) - Get help with errors