> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beaconcha.in/llms.txt
> Use this file to discover all available pages before exploring further.
# API Error Messages
> Complete reference for beaconcha.in API error messages, what they mean, and how to handle them.
## Overview
All API errors use this shape unless otherwise noted:
```json theme={null}
{
"error": "message text"
}
```
Use the HTTP status code as the primary signal. Treat the `error` string as human-readable context that may vary by endpoint.
In rare panic-recovery cases, the server may return a plain-text `500 Internal Server Error` body instead of JSON.
## Errors shown in API Reference examples
These are the shared examples shown across API Reference response tabs:
| HTTP | Example message | Meaning | Recommended action |
| --------- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `400` | `Bad request. Please check your input and try again.` | Request payload/params are invalid. | Validate request shape and values against the endpoint schema. |
| `401` | `Unauthorized. Please provide a valid API key.` | Authentication failed. | Send `Authorization: Bearer ` with a valid key. |
| `403` | `endpoint not allowed for your subscription tier. upgrade your subscription at https://beaconcha.in/pricing.` | Authenticated, but plan/permissions do not allow this endpoint or selector. | Upgrade plan, reduce selector scope, or switch to an allowed endpoint. |
| `404` | `The requested resource was not found.` | Requested resource/data was not found. | Check identifiers/ranges and retry with existing data. |
| `429` | `Rate limit exceeded. Please try again later.` | Request limit exceeded. | Back off and retry after `ratelimit-reset`. |
| `default` | `An unexpected error occurred.` | Generic fallback example. | Retry with backoff; if persistent, contact support with request details. |
## Complete Runtime Error Catalog (Public v2 API)
The following messages are returned by the current backend implementation for public **v2 API** endpoints and may be more specific than the shared examples above.
This guide is for public **v2 API** behavior. Public **v1 API** endpoints may return different status codes and message texts.
### `401 Unauthorized`
| Message | Common causes | Recommended user action |
| ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `API key missing from authorization header. You can obtain a free API key at https://beaconcha.in/register` | Missing `Authorization` header. | Send `Authorization: Bearer `. |
| `invalid authorization format` | Header is not `Bearer `, malformed token, extra spaces/prefix. | Use exact Bearer format and a raw API key. |
| `invalid API key` | Unknown/revoked key, key/user not found. | Regenerate key in user settings and update your client secret store. |
Internal API (session-based) also returns:
| Message | Common causes | Recommended user action |
| ------------------------ | ---------------------------------------------- | ------------------------------------------------------------------- |
| `Missing session cookie` | Session cookie is absent on internal API call. | Authenticate in the app first and send the required session cookie. |
| `Invalid session ID` | Session is expired, malformed, or unknown. | Re-authenticate and retry with a fresh session. |
### `403 Forbidden`
| Message | Common causes | Recommended user action |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `endpoint not allowed for your subscription tier. upgrade your subscription at https://beaconcha.in/pricing.` | Your current plan does not include the requested capability. | Upgrade plan or use a capability available on your tier. |
| `number of validator identifiers exceeds allowed limit of for your subscription tier. upgrade your subscription at https://beaconcha.in/pricing.` | Too many validator IDs/public keys in one request for your tier. | Reduce selector size, split into smaller batches, or upgrade. |
| `validator selector type not allowed for your subscription tier. upgrade your subscription at https://beaconcha.in/pricing.` | Using premium selector types (`deposit_address`, `withdrawal`, etc.) on non-premium tier. | Use allowed selector types or upgrade. |
| `maximum number of API keys () reached` | Internal API key-management quota reached. | Delete unused keys or increase allowed limit via plan/support. |
### `404 Not Found`
| Message | Common causes | Recommended user action |
| ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------- |
| `block root not found` | Unknown consensus block root. | Verify root format/network and retry with an existing root. |
| `dashboard or group not found for your user account` | Dashboard/group ID does not exist or is not accessible to this API key's user. | Confirm ownership/permissions and IDs. |
| `no sub-entities found for entity ''` | Entity has no sub-entities for requested window/filters. | Check entity spelling/window and try broader range. |
| `slot not found` | Slot is outside indexed/available data. | Re-check chain/slot and query an existing slot. |
| `requested slot is before the earliest available slot with sync committee duties ` | Requested slot predates available sync committee duties data. | Query a later slot at or after ``. |
| `requested slot is greater than latest slot ` | Requested slot is beyond the latest known slot for the selected view (`head`/`finalized`). | Retry with a lower slot or use `head`/`finalized` selectors. |
| `requested sync committee period is before the earliest available period ` | Requested period predates available history. | Use a period `>= `. |
| `requested sync committee period is beyond the latest available period ` | Requested period is too far in the future. | Query `latest`/`next` or a lower explicit period. |
| `requested sync committee period is beyond the latest available and finalized period ` | Requested period exceeds the range of finalized periods for that endpoint. | Query `latest` or a lower finalized period. |
| `requested sync committee period not found` | No committee data exists for that period. | Verify period value and retry with a known available period. |
| `Requesting the 'next' sync committee period is currently not supported by this endpoint. This feature may soon be available in a future update.` | Endpoint does not support `next` for this operation. | Use an explicit existing period or `latest` where supported. |
| `no indexed data found for block ` | Block exists but indexed data for that endpoint is unavailable. | Try another block or retry later after indexing catches up. |
| `no validators found` | Validator selector resolved to no records. | Check validator IDs/public keys/entity input. |
| `no validators found for the provided validator selector` | Selector is syntactically valid but empty in data. | Confirm selector and chain, then retry. |
| `no validators found for the provided selector` | Selector did not resolve to any validators. | Confirm selector values and chain context, then retry. |
| `no APY & ROI data available for the requested range and validators` | No ROI dataset for requested validators/window. | Use a different window or selector with active validators. |
| `no attestation assignment data available for the requested validators` | No attestation history for selected validators. | Check validator activity and query a different range. |
| `no validator balances available for the requested epoch ` | No balances for that epoch/selector. | Verify epoch/finality and retry with available epoch. |
| `no validator performance data available for the requested epoch ` | No performance row for that epoch/selector. | Check epoch/selector and try adjacent epoch. |
| `no validator performance data available for the requested range and validators` | No performance data in selected window. | Expand range or adjust validator set. |
| `no validator rewards data available for the requested epoch ` | No rewards row for that epoch/selector. | Verify epoch/selector and retry with available epoch. |
| `no validator rewards data available for the requested range and validators` | No rewards in selected window. | Expand range or adjust validator set. |
| `no validator metadata available for the requested validators` | Metadata missing for selected validators. | Check selector and ensure validators exist on target chain. |
| `API key not found: ` | Internal API key-management request referenced a non-existent key name. | Verify key name or list keys before update/delete operations. |
| `resource not found` | Domain-level not found fallback. | Re-check target resource identifiers and retry. |
| `path not found: ` | Route does not exist. | Fix URL path; use API Reference path exactly. |
### `400 Bad Request`
| Message | Common causes | Recommended user action |
| ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `empty request body` | Missing JSON body on required POST endpoint. | Send `Content-Type: application/json` and valid body. |
| `parameter "cursor" is invalid` | Cursor is malformed, stale, or from another endpoint/query. | Use `paging.next_cursor` from the same endpoint and unchanged filters/sorting. |
| `evaluation_window 'all_time' is not supported for this endpoint` | `all_time` used where endpoint supports only bounded windows. | Use `24h`, `7d`, `30d`, or `90d` as documented. |
| `sort_by and sort_order must not change between paginated requests; start a new query without a cursor to change sorting` | Changed sort options mid-pagination. | Keep sort stable while using a cursor, or restart without cursor. |
| `entity must be provided` | Missing `entity` field for sub-entity queries. | Provide `entity` in request body. |
| `invalid block root hex` | Block root is not valid hex. | Send `0x`-prefixed valid hex root. |
| `invalid time range: start epoch is after end epoch ` | Inverted epoch range. | Swap/fix boundaries so start is not greater than end. |
| `invalid time range: start slot is after end slot ` | Inverted slot range. | Swap/fix boundaries so start is not greater than end. |
| `invalid time range: start time is after end time ` | Inverted timestamp range. | Swap/fix boundaries so start is not greater than end. |
### `405 Method Not Allowed`
| Message | Common causes | Recommended user action |
| ------------------------------ | -------------------------------------------------------- | ---------------------------------------- |
| `method not allowed: ` | Wrong HTTP method (for example `GET` instead of `POST`). | Use the method defined in API Reference. |
### `409 Conflict`
| Message | Common causes | Recommended user action |
| ------------------------------------------- | ------------------------------------------------------------------------ | --------------------------------------------- |
| `API key with name '' already exists` | Creating an API key with a duplicate name (internal API key management). | Use a unique key name or rename existing key. |
### `429 Too Many Requests`
| Message | Common causes | Recommended user action |
| --------------------- | -------------------------------------------------- | ------------------------------------------------------------------ |
| `rate limit exceeded` | Per-second/minute/hour/day/month bucket exhausted. | Pause and retry after `ratelimit-reset`; implement backoff/jitter. |
### `500 Internal Server Error`
| Message | Common causes | Recommended user action |
| ------------------------------------------------ | --------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `internal server error. please try again later.` | Unexpected server-side error. | Retry with exponential backoff; contact support if persistent. |
| `Internal Server Error` | Panic recovery fallback response. | Retry once; if persistent, report with timestamp and request ID details. |
| `failed to encode response` | Rare server-side serialization failure (health/operational handlers). | Retry once; if repeated, report with timestamp and endpoint. |
## Dynamic validation error format
For schema/validation failures, the API can return structured, field-level messages generated at runtime (for example missing required fields or enum/type mismatch). Typical patterns:
* `request body: : is missing`
* `request body: : input must be one of `
* `request body: : input must not be null`
* `request body: : doesn't match expected schema due to one of the following reasons: {...}`
Recommended handling:
1. Treat all `400` as non-retryable until request is fixed.
2. Surface the raw `error` text in logs for faster debugging.
3. Add client-side schema validation for high-volume paths.
## Client handling checklist
1. Parse JSON body and capture `status`, `error`, and rate-limit headers.
2. Retry only retryable statuses (`429`, and selected `5xx`) with backoff.
3. Do not retry `400`, `401`, `403`, `404`, `405` blindly.
4. Keep pagination inputs stable (`cursor`, filters, sort options).
5. Include endpoint, request payload hash, timestamp, and error text in logs.