API Error Messages

Overview

All API errors use this shape unless otherwise noted:

{
  "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 <API_KEY>` 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 <API_KEY>`.
`invalid authorization format`	Header is not `Bearer <token>`, 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 <allowedCount> 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 (<maxKeys>) 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>'`	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 <slot> is before the earliest available slot with sync committee duties <firstAltairSlot>`	Requested slot predates available sync committee duties data.	Query a later slot at or after `<firstAltairSlot>`.
`requested slot <slot> is greater than latest <view> slot <latestSlot>`	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 <period> is before the earliest available period <earliest>`	Requested period predates available history.	Use a period `>= <earliest>`.
`requested sync committee period <period> is beyond the latest available period <latestPlusOne>`	Requested period is too far in the future.	Query `latest`/`next` or a lower explicit period.
`requested sync committee period <period> is beyond the latest available and finalized period <latestPeriod>`	Requested period exceeds the range of finalized periods for that endpoint.	Query `latest` or a lower finalized period.
`requested sync committee period <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>`	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 <epoch>`	No balances for that epoch/selector.	Verify epoch/finality and retry with available epoch.
`no validator performance data available for the requested epoch <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 <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: <name>`	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: <path>`	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 <startEpoch> is after end epoch <endEpoch>`	Inverted epoch range.	Swap/fix boundaries so start is not greater than end.
`invalid time range: start slot <startSlot> is after end slot <endSlot>`	Inverted slot range.	Swap/fix boundaries so start is not greater than end.
`invalid time range: start time <startTime> is after end time <endTime>`	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: <method>`	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 '<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: <field>: is missing
request body: <field>: input must be one of <allowed_values>
request body: <field>: input must not be null
request body: <field>: doesn't match expected schema due to one of the following reasons: {...}

Recommended handling:

Treat all 400 as non-retryable until request is fixed.
Surface the raw error text in logs for faster debugging.
Add client-side schema validation for high-volume paths.

Client handling checklist

Parse JSON body and capture status, error, and rate-limit headers.
Retry only retryable statuses (429, and selected 5xx) with backoff.
Do not retry 400, 401, 403, 404, 405 blindly.
Keep pagination inputs stable (cursor, filters, sort options).
Include endpoint, request payload hash, timestamp, and error text in logs.

Introduction

V2 API Docs

V1 API Docs

Overview

Errors shown in API Reference examples

Complete Runtime Error Catalog (Public v2 API)

`401 Unauthorized`

`403 Forbidden`

`404 Not Found`

`400 Bad Request`

`405 Method Not Allowed`

`409 Conflict`

`429 Too Many Requests`

`500 Internal Server Error`

Dynamic validation error format

Client handling checklist

​Overview

​Errors shown in API Reference examples

​Complete Runtime Error Catalog (Public v2 API)

​401 Unauthorized

​403 Forbidden

​404 Not Found

​400 Bad Request

​405 Method Not Allowed

​409 Conflict

​429 Too Many Requests

​500 Internal Server Error

​Dynamic validation error format

​Client handling checklist

Overview

Errors shown in API Reference examples

Complete Runtime Error Catalog (Public v2 API)

`401 Unauthorized`

`403 Forbidden`

`404 Not Found`

`400 Bad Request`

`405 Method Not Allowed`

`409 Conflict`

`429 Too Many Requests`

`500 Internal Server Error`

Dynamic validation error format

Client handling checklist