> ## 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.

# Errores

> El formato de los errores, los códigos estables y cómo distinguir una falla de la fuente de un resultado vacío.

## Formato

Todo error responde JSON con un `detail` legible:

```json theme={null}
{ "detail": "Mensaje que explica el problema." }
```

Cuando el cliente necesita reaccionar a un caso concreto, el cuerpo trae además `error`: un **código estable** que no
cambia aunque cambie el texto. Programá contra `error`, no contra `detail`.

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

> [!NOTE]
>
> Los errores de validación de parámetros (`422`) usan el formato estándar: `detail` es una lista con el campo y el
> problema de cada uno.

## Status

| Status | Qué significa |
| - | - |
| `400` | El pedido no es válido: una dirección o un hash mal formados, una red que no está soportada (la respuesta nombra las que sí) o un header que no corresponde. |
| `401` | Falta la clave o no es válida. |
| `402` | Se agotó el cupo mensual de créditos. |
| `403` | No tenés permiso para eso (ver los códigos abajo). |
| `404` | No existe, o existe pero no lo podés ver. Las dos cosas responden igual a propósito. |
| `409` | Hace falta que elijas algo: por ejemplo, una transacción de pérdida con varios orígenes posibles; la respuesta trae los candidatos. |
| `422` | Faltan parámetros o tienen un tipo incorrecto. |
| `429` | Superaste el rate limit; esperá lo que dice `Retry-After`. |
| `503` | No se pudo leer lo que pediste: la fuente de datos falló (`source_unavailable`). |

Ningún error consume créditos.

## Códigos estables más comunes

| `error` | Status | Cuándo |
| - | - | - |
| `read_only` | 403 | Tu rol o tu clave son de solo lectura y la ruta guarda algo. |
| `key_scope` | 403 | La clave de la organización no tiene ese recurso entre sus `scopes`. |
| `case_unavailable` | 400 | El `X-Case-Id` nombra un caso que no existe, se borró o ya no está compartido con vos. La consulta no se hizo. |
| `case_read_only` | 403 | Intentaste guardar un caso que tenés compartido solo para ver. |
| `source_unavailable` | 503 | La fuente de datos no pudo leer lo que pediste. |

Hay otros, propios de cada familia de endpoints y documentados en la referencia. Por ejemplo, `ai_disabled` (403)
cuando tu organización apagó la IA o la búsqueda web, y los de las auditorías:
`bad_id`, `audit_id_mismatch`, `not_found`, `unknown_section` y `audit_source_unavailable`.

## Falla de la fuente o resultado vacío

Cada lectura a una fuente de datos termina en una de tres cosas: **datos**, un **vacío que la fuente afirmó** o una
**falla**. Una falla nunca se presenta como «no hay datos».

> [tab] Falló lo que pediste
>
> Si no se pudo leer la dirección o la transacción que pediste, la respuesta es `503` con el motivo estructurado y
> **sin cobro**:
>
> ```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"
> }
> ```
>
> Si viene `retry_after`, la respuesta trae también el header `Retry-After`.

> [tab] Falló un paso intermedio
>
> Si falló un paso intermedio (expandir un nodo del rastreo, verificar un bridge, clasificar una dirección), la
> respuesta es `200`, **se cobra** y lo declara:
>
> * `degraded_sources`: cada falla con su `stage`, su `reason` y su efecto;
> * `coverage_gaps` en el nodo o la arista afectados.
>
> En un nodo marcado, la ausencia de datos **no** es ausencia de movimientos.

Ninguna falla se guarda en la cache: la próxima consulta vuelve a preguntarle a la fuente.

### Motivos (`reason`)

| `reason` | ¿Reintentar? | Qué pasó |
| - | - | - |
| `rate_limited` | Sí | Límite de consultas por segundo de la fuente. |
| `timeout` | Sí | La fuente no respondió a tiempo. |
| `network` | Sí | Error de red al conectar con la fuente. |
| `upstream_error` | Sí | La fuente devolvió un error. |
| `rpc_error` | Sí | El nodo de la red devolvió un error. |
| `invalid_response` | Sí | La fuente respondió con un formato inesperado. |
| `circuit_open` | Sí | La fuente quedó en pausa por fallas seguidas; siempre viene con `retry_after`. |
| `quota_exhausted` | No | Se agotó la cuota diaria o de créditos de la fuente; se renueva sola. |
| `not_in_plan` | No | La fuente no sirve esa red o esa consulta con el plan actual. |
| `unauthorized` | No | La fuente rechazó el acceso. |
| `unsupported` | No | El proveedor de esa red no implementa esa consulta. |
| `not_configured` | No | No hay fuente configurada para esa red. |
| `bad_request` | No | La fuente rechazó la consulta. |
| `incomplete_index` | No | La fuente respondió, pero su índice no cubre todo lo pedido. |
| `unsupported_chain` | No | El rastreo cruzó (por un bridge) a una red que Blockgence no consulta: ese tramo quedó sin rastrear. |
| `not_in_registry` | No | La red se consulta, pero a Blockgence le falta registrado el contrato o el id de ese protocolo: la consulta no se hizo. |
| `budget_exhausted` | No | Se alcanzó un tope de Blockgence (filas, lecturas por consulta o un cupo diario). No es una falla de la fuente. |
| `internal_error` | No | Error interno de Blockgence, no de la fuente. |

`source_fault` dice si fue una falla de la fuente (`true`) o un tope o una consulta que no se hizo (`false`), y
`failure_cause` explica por qué, en una frase.

> [!TIP]
>
> Para saber si una fuente está caída y hasta cuándo, consultá `GET /v1/sources` (sin costo).


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