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

# Errores

> Formato de error de /connect/v1 y enlaces doc_url.

Las respuestas de error de Connect usan un envelope consistente:

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "idempotency_key_required",
    "message": "Idempotency-Key header is required for this endpoint.",
    "param": null,
    "doc_url": "https://docs.zopay.cash/errors/idempotency_key_required"
  }
}
```

## Campos

| Campo     | Descripción                                                                                 |
| --------- | ------------------------------------------------------------------------------------------- |
| `type`    | Categoría (por ejemplo `authentication_error`, `invalid_request_error`, `not_found_error`). |
| `code`    | Código legible por máquina.                                                                 |
| `message` | Mensaje para humanos.                                                                       |
| `param`   | Campo de entrada relacionado, si aplica.                                                    |
| `doc_url` | URL base `https://docs.zopay.cash/errors/` + `code`.                                        |

## Códigos frecuentes

| Código                            | HTTP típico | Cuándo                                                                                                                                                                           |
| --------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `authentication_required`         | 401         | Sin header, clave inválida o malformada.                                                                                                                                         |
| `expired_credential`              | 401         | Clave con `expires_at` en el pasado. Rota desde el panel. Ver [Autenticación](/api-reference/authentication).                                                                    |
| `account_pending_approval`        | 403         | Cuenta Connect no aprobada en endpoints que mueven fondos.                                                                                                                       |
| `forbidden_scope`                 | 403         | La clave no tiene el scope requerido por el endpoint. Mintea una nueva o extiende los scopes.                                                                                    |
| `not_yet_available`               | 501         | Endpoint registrado pero sin implementación aún.                                                                                                                                 |
| `idempotency_key_required`        | 400         | Falta `Idempotency-Key` en rutas que lo exigen.                                                                                                                                  |
| `idempotency_conflict`            | 409         | Misma `Idempotency-Key` con body distinto.                                                                                                                                       |
| (validación de body)              | 422         | Body estructuralmente inválido (campo faltante, tipo equivocado). `error.param` nombra la llave. Ver [422 vs 400](/api-reference/idempotency#errores-de-validación--422-vs-400). |
| `catalog_invalid`                 | 400         | Asset desconocido. Verifica con [`GET /capabilities`](/api-reference/endpoints/get-capabilities).                                                                                |
| `min_usdt_amount_requires_solana` | 400         | USDT en red no-Solana con `amount <= 5.5`. Ver [Reglas de selección de red](/api-reference/network-rules).                                                                       |
| `event_not_found`                 | 404         | `evt_…` no existe en tu tenant. Misma forma de envelope que un id cross-tenant — los eventos no son enumerables entre orgs.                                                      |
| `webhook_endpoint_not_configured` | 400         | Llamaste a [`POST /events/:id/replay`](/api-reference/endpoints/post-events-by-id-replay) pero no tienes un webhook habilitado. Configúralo y reintenta.                         |

Errores de autenticación detallados en [Autenticación](/api-reference/authentication). Idempotencia en [Idempotencia](/api-reference/idempotency). Eventos en [Events](/api-reference/events).