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

# Errors

> The error format, the stable codes and how to tell a source failure from an empty result.

## Format

Every error returns JSON with a readable `detail`:

```json theme={null}
{ "detail": "Message that explains the problem." }
```

When the client needs to react to a specific case, the body also carries `error`: a **stable code** that does not
change even if the text does. Code against `error`, not against `detail`.

```json theme={null}
{ "error": "key_scope", "detail": "Esta API key no tiene permiso para «trace». Sus recursos: cases." }
```

> [!NOTE]
>
> Error messages (`detail`) are in Spanish. Stable codes (`error`) and field names are the same in every language.

Parameter validation errors (`422`) use the standard format: `detail` is a list with each field and its problem.

## Status codes

| Status | Meaning |
| - | - |
| `400` | The request is not valid: a malformed address or hash, an unsupported network (the response lists the supported ones) or a header that does not match. |
| `401` | The key is missing or invalid. |
| `402` | The monthly credit quota is used up. |
| `403` | You are not allowed to do that (see the codes below). |
| `404` | It does not exist, or it exists but you cannot see it. Both return the same on purpose. |
| `409` | You need to choose something: for example, a loss transaction with several possible origins; the response carries the candidates. |
| `422` | Parameters are missing or have the wrong type. |
| `429` | You went over the rate limit; wait the time given in `Retry-After`. |
| `503` | What you asked for could not be read: the data source failed (`source_unavailable`). |

No error uses credits.

## Most common stable codes

| `error` | Status | When |
| - | - | - |
| `read_only` | 403 | Your role or your key is read-only and the path saves something. |
| `key_scope` | 403 | The organization key does not have that resource among its `scopes`. |
| `case_unavailable` | 400 | `X-Case-Id` names a case that does not exist, was deleted or is no longer shared with you. The query was not run. |
| `case_read_only` | 403 | You tried to save a case shared with you for viewing only. |
| `source_unavailable` | 503 | The data source could not read what you asked for. |

There are others, specific to each endpoint family and documented in the reference. For example, `ai_disabled` (403)
when your organization turned off AI or web search, and the audit codes: `bad_id`,
`audit_id_mismatch`, `not_found`, `unknown_section` and `audit_source_unavailable`.

## Source failure or empty result

Every read from a data source ends in one of three ways: **data**, an **empty result the source asserted**, or a
**failure**. A failure is never presented as «no data».

> [tab] What you asked for failed
>
> If the address or transaction you asked for could not be read, the response is `503` with a structured reason and
> **no charge**:
>
> ```json theme={null}
> {
>   "error": "source_unavailable",
>   "detail": "La fuente etherscan falló en ethereum (get_transfers · 0x098b…2f96): límite de consultas por segundo de la fuente. Reintentá en 2 s. No se cobraron créditos por esta consulta.",
>   "source": "etherscan",
>   "chain": "ethereum",
>   "primitive": "get_transfers",
>   "operation": "",
>   "target": "0x098b716b8aaf21512996dc57eb0615e2383e2f96",
>   "reason": "rate_limited",
>   "retryable": true,
>   "http_status": null,
>   "retry_after": 2,
>   "upstream_message": "",
>   "source_fault": true,
>   "failure_cause": "etherscan: límite de consultas por segundo de la fuente"
> }
> ```
>
> When `retry_after` is present, the response also carries the `Retry-After` header.

> [tab] An intermediate step failed
>
> If an intermediate step failed (expanding a trace node, verifying a bridge, classifying an address), the response is
> `200`, **is charged** and declares it:
>
> * `degraded_sources`: each failure with its `stage`, its `reason` and its effect;
> * `coverage_gaps` on the affected node or edge.
>
> On a flagged node, missing data is **not** the same as no movements.

No failure is cached: the next query asks the source again.

### Reasons (`reason`)

| `reason` | Retry? | What happened |
| - | - | - |
| `rate_limited` | Yes | The source's per-second query limit. |
| `timeout` | Yes | The source did not answer in time. |
| `network` | Yes | Network error connecting to the source. |
| `upstream_error` | Yes | The source returned an error. |
| `rpc_error` | Yes | The network node returned an error. |
| `invalid_response` | Yes | The source answered in an unexpected format. |
| `circuit_open` | Yes | The source was paused after repeated failures; it always comes with `retry_after`. |
| `quota_exhausted` | No | The source's daily or credit quota is used up; it renews on its own. |
| `not_in_plan` | No | The source does not serve that network or query with the current plan. |
| `unauthorized` | No | The source refused access. |
| `unsupported` | No | That network's provider does not implement that query. |
| `not_configured` | No | No source is configured for that network. |
| `bad_request` | No | The source rejected the query. |
| `incomplete_index` | No | The source answered, but its index does not cover everything asked for. |
| `unsupported_chain` | No | The trace crossed (through a bridge) into a network Blockgence does not query: that segment was not traced. |
| `not_in_registry` | No | The network is queried, but Blockgence lacks that protocol's contract or id in its registry: the query was not made. |
| `budget_exhausted` | No | A Blockgence cap was reached (rows, reads per query or a daily quota). It is not a failure of the source. |
| `internal_error` | No | An internal Blockgence error, not the source's. |

`source_fault` says whether it was a failure of the source (`true`) or a cap or a query that was not made (`false`), and
`failure_cause` explains why, in one sentence.

> [!TIP]
>
> To find out whether a source is down and until when, query `GET /v1/sources` (free).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.