# Errores

> El formato de los errores y qué hacer con cada código.

Source: https://piqline.com/es/docs/api/errors

Todos los errores de la API son una respuesta `application/problem+json`, en el formato RFC 9457:

```json
{
  "type": "https://piqline.com/docs/api/errors#insufficient_scope",
  "title": "Scope insuffisant",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "searchWeb demande le scope explore.",
  "request_id": "8c0c051b-c3e6-4fa0-8b98-0aa227cf3c2a",
  "missing_scopes": ["explore"]
}
```

| Campo | Significado |
| --- | --- |
| `type` | la URL de la sección de esta página que describe el error |
| `title` | un título corto, en francés |
| `status` | el estado HTTP |
| `code` | el identificador estable del error: prueba este |
| `detail` | una explicación legible, en francés, que puede cambiar entre versiones |
| `request_id` | el ID de la petición, también en la cabecera `X-Request-Id` |

Según el error, se añaden otros campos: `missing_scopes`, `issues`.

Cuando nos escribas, cita el `request_id`. Permite encontrar la petición en nuestros registros y, si la clave era válida, en el historial de Ajustes → API y MCP. El formulario está en la [página de contacto](/contact).

## Códigos

### `missing_key`

**401** · Falta la clave de API

**Causa.** La petición no incluye ninguna clave.

**Qué hacer.** Envía `Authorization: Bearer piq_live_…` (o `x-api-key`).

### `invalid_key`

**401** · Clave de API no válida

**Causa.** La clave tiene un formato incorrecto (copia truncada o reescrita), es desconocida, está revocada o caducada, o su creador ha abandonado el workspace. `detail` distingue un problema de formato de un problema de estado.

**Qué hacer.** Revisa la copia. Si la clave está revocada o caducada, crea una nueva en Ajustes → API y MCP.

### `insufficient_scope`

**403** · Scope insuficiente

**Causa.** A la clave le falta un scope que exige la ruta o la herramienta. `missing_scopes` los lista.

**Qué hacer.** Crea una clave con esos scopes. Una clave existente conserva sus scopes: no se pueden cambiar.

### `forbidden`

**403** · Prohibido

**Causa.** El rol del creador de la clave no da acceso a esta herramienta o agente.

**Qué hacer.** Crea la clave desde una cuenta que tenga el rol requerido (propietario o administrador para las herramientas de escritura y de acción, y para el agente onboarding).

### `not_found`

**404** · No encontrado

**Causa.** Ruta, herramienta o agente desconocidos. Las tarjetas interactivas del chat (`askUser`, `proposeSources`, `proposeBoard`…) no son herramientas invocables.

**Qué hacer.** Lista los nombres válidos con `GET /api/v1/tools` y `GET /api/v1/agents`.

### `invalid_input`

**422** · Entrada no válida

**Causa.** El cuerpo no es JSON válido, o la entrada no coincide con el esquema de la herramienta. `issues` señala cada campo erróneo (`path`, `message`).

**Qué hacer.** Compara tu cuerpo con el `input_schema` de la herramienta (`GET /api/v1/tools/{nom}`).

### `tool_error`

**422** · Error de herramienta

**Causa.** La herramienta rechazó la petición por un motivo propio de tus datos, por ejemplo un elemento que no existe en este workspace. `detail` indica el motivo.

**Qué hacer.** Corrige la entrada según `detail`. La misma llamada da la misma respuesta mientras no cambie nada.

### `rate_limited`

**429** · Demasiadas peticiones

**Causa.** La clave ha superado su límite por minuto.

**Qué hacer.** Espera el número de segundos indicado en la cabecera `Retry-After` y vuelve a intentarlo. Espacia tus llamadas.

### `quota_exceeded`

**429** · Cuota diaria alcanzada

**Causa.** La clave ha alcanzado su tope diario de peticiones. El contador se reinicia cada día a medianoche UTC.

**Qué hacer.** Vuelve a intentarlo después de medianoche UTC. Para subir el tope, escríbenos desde la [página de contacto](/contact).

### `budget_exhausted`

**402** · Créditos mensuales agotados

**Causa.** El workspace de la clave ha alcanzado su tope mensual de créditos. Todo lo que gasta (agentes, herramientas de pago, recogida) se rechaza antes de la llamada, y un turno de agente en curso se detiene al llegar al tope. `detail` indica la fecha de reanudación.

**Qué hacer.** Espera la fecha de reanudación indicada en `detail`, o pide a un propietario del workspace que suba el tope.

### `plan_restricted`

**403** · No incluido en el plan

**Causa.** El plan del workspace de la clave no permite esta petición: no abre la API, o la abre en solo lectura y la petición escribe, se suscribe, o inicia una investigación o un agente. `plan` indica el plan y `api_access` el acceso (`none`, `read`).

**Qué hacer.** Pide a Piqline un plan que abra el acceso que necesitas: Équipe para lectura, Business para acceso completo.

### `unavailable`

**503** · Servicio no disponible

**Causa.** Un servicio del que depende la petición no responde: verificación de la clave, modelo del agente o proveedor.

**Qué hacer.** Vuelve a intentarlo con una espera creciente. Si el error persiste, cita `request_id` cuando nos escribas.

### `not_configured`

**503** · No configurado

**Causa.** La API no está configurada en el servidor: falta una variable de entorno.

**Qué hacer.** Cita `request_id` cuando nos escribas: solo Piqline puede resolver este caso.

### `internal`

**500** · Error interno

**Causa.** Error inesperado por parte de Piqline. `detail` es vago a propósito.

**Qué hacer.** Vuelve a intentarlo. Si el error persiste, cita `request_id` cuando nos escribas.
