# Errori

> Il formato degli errori e che cosa fare per ogni codice.

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

Ogni errore dell'API è una risposta `application/problem+json`, nel 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 | Significato |
| --- | --- |
| `type` | l'URL della sezione di questa pagina che descrive l'errore |
| `title` | un titolo breve, in francese |
| `status` | lo stato HTTP |
| `code` | l'identificatore stabile dell'errore: testa questo |
| `detail` | una spiegazione leggibile, in francese, che può cambiare tra le versioni |
| `request_id` | l'ID della richiesta, presente anche nell'header `X-Request-Id` |

A seconda dell'errore, vengono aggiunti altri campi: `missing_scopes`, `issues`.

Quando ci scrivi, indica il `request_id`. Permette di ritrovare la richiesta nei nostri log e, se la chiave era valida, nella cronologia di Impostazioni → API e MCP. Il modulo è nella [pagina dei contatti](/contact).

## Codici

### `missing_key`

**401** · Chiave API mancante

**Causa.** La richiesta non contiene alcuna chiave.

**Che cosa fare.** Invia `Authorization: Bearer piq_live_…` (oppure `x-api-key`).

### `invalid_key`

**401** · Chiave API non valida

**Causa.** La chiave è malformata (copia troncata o ridigitata), sconosciuta, revocata o scaduta, oppure il suo creatore ha lasciato il workspace. `detail` distingue un problema di formato da un problema di stato.

**Che cosa fare.** Controlla la copia. Se la chiave è revocata o scaduta, creane una nuova in Impostazioni → API e MCP.

### `insufficient_scope`

**403** · Scope insufficiente

**Causa.** Alla chiave manca uno scope richiesto dalla route o dal tool. `missing_scopes` li elenca.

**Che cosa fare.** Crea una chiave con quegli scope. Una chiave esistente mantiene i suoi scope: non possono essere modificati.

### `forbidden`

**403** · Accesso negato

**Causa.** Il ruolo del creatore della chiave non dà accesso a questo tool o a questo agente.

**Che cosa fare.** Crea la chiave da un account che ha il ruolo richiesto (owner o admin per i tool di scrittura e di azione, e per l'agente onboarding).

### `not_found`

**404** · Non trovato

**Causa.** Route, tool o agente sconosciuto. Le card interattive della chat (`askUser`, `proposeSources`, `proposeBoard`…) non sono tool richiamabili.

**Che cosa fare.** Elenca i nomi validi con `GET /api/v1/tools` e `GET /api/v1/agents`.

### `invalid_input`

**422** · Input non valido

**Causa.** Il corpo non è JSON valido, oppure l'input non corrisponde allo schema del tool. `issues` indica ogni campo errato (`path`, `message`).

**Che cosa fare.** Confronta il tuo corpo con l'`input_schema` del tool (`GET /api/v1/tools/{nom}`).

### `tool_error`

**422** · Errore del tool

**Causa.** Il tool ha rifiutato la richiesta per un motivo legato ai tuoi dati, per esempio un elemento che non esiste in questo workspace. `detail` indica il motivo.

**Che cosa fare.** Correggi l'input secondo `detail`. La stessa chiamata dà la stessa risposta finché nulla cambia.

### `rate_limited`

**429** · Troppe richieste

**Causa.** La chiave ha superato il limite al minuto.

**Che cosa fare.** Attendi il numero di secondi indicato nell'header `Retry-After`, poi riprova. Distanzia le chiamate.

### `quota_exceeded`

**429** · Quota giornaliera raggiunta

**Causa.** La chiave ha raggiunto il limite giornaliero di richieste. Il contatore si azzera ogni giorno a mezzanotte UTC.

**Che cosa fare.** Riprova dopo la mezzanotte UTC. Per aumentare il limite, scrivici dalla [pagina dei contatti](/contact).

### `budget_exhausted`

**402** · Crediti mensili esauriti

**Causa.** Il workspace della chiave ha raggiunto il limite mensile di crediti. Tutto ciò che consuma (agenti, tool a pagamento, raccolta) viene rifiutato prima della chiamata, e un turno di agente in corso si ferma quando raggiunge il limite. `detail` indica la data di ripresa.

**Che cosa fare.** Attendi la data di ripresa indicata in `detail`, oppure chiedi a un owner del workspace di aumentare il limite.

### `plan_restricted`

**403** · Non incluso nel piano

**Causa.** Il piano del workspace della chiave non consente questa richiesta: non apre l'API, oppure la apre in sola lettura e la richiesta scrive, si iscrive, o avvia un'indagine o un agente. `plan` indica il piano e `api_access` l'accesso (`none`, `read`).

**Che cosa fare.** Chiedi a Piqline un piano che apra l'accesso di cui hai bisogno: Équipe per la lettura, Business per l'accesso completo.

### `unavailable`

**503** · Servizio non disponibile

**Causa.** Un servizio da cui dipende la richiesta non risponde: verifica della chiave, modello dell'agente o provider.

**Che cosa fare.** Riprova con un intervallo crescente. Se l'errore persiste, indica `request_id` quando ci scrivi.

### `not_configured`

**503** · Non configurato

**Causa.** L'API non è configurata sul server: manca una variabile d'ambiente.

**Che cosa fare.** Indica `request_id` quando ci scrivi: solo Piqline può risolvere questo caso.

### `internal`

**500** · Errore interno

**Causa.** Errore imprevisto lato Piqline. `detail` resta volutamente vago.

**Che cosa fare.** Riprova. Se l'errore persiste, indica `request_id` quando ci scrivi.
