Overview
All API errors use this shape unless otherwise noted: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. |
| 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 missingrequest body: <field>: input must be one of <allowed_values>request body: <field>: input must not be nullrequest body: <field>: doesn't match expected schema due to one of the following reasons: {...}
- Treat all
400as non-retryable until request is fixed. - Surface the raw
errortext 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 selected5xx) with backoff. - Do not retry
400,401,403,404,405blindly. - Keep pagination inputs stable (
cursor, filters, sort options). - Include endpoint, request payload hash, timestamp, and error text in logs.