# Fehler

> Das Fehlerformat und was bei jedem Code zu tun ist.

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

Jeder API-Fehler ist eine Antwort `application/problem+json` im Format von 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"]
}
```

| Feld | Bedeutung |
| --- | --- |
| `type` | die URL des Abschnitts dieser Seite, der den Fehler beschreibt |
| `title` | ein kurzer Titel, auf Französisch |
| `status` | der HTTP-Status |
| `code` | die stabile Kennung des Fehlers: Prüfen Sie diese |
| `detail` | eine lesbare Erklärung, auf Französisch, die sich zwischen Versionen ändern kann |
| `request_id` | die ID der Anfrage, auch im Header `X-Request-Id` |

Je nach Fehler kommen weitere Felder hinzu: `missing_scopes`, `issues`.

Nennen Sie uns bei einer Nachricht die `request_id`. Damit finden wir die Anfrage in unseren Logs und, wenn der Schlüssel gültig war, im Verlauf unter Einstellungen → API und MCP. Das Formular finden Sie auf der [Kontaktseite](/contact).

## Codes

### `missing_key`

**401** · API-Schlüssel fehlt

**Ursache.** Die Anfrage enthält keinen Schlüssel.

**Was zu tun ist.** Senden Sie `Authorization: Bearer piq_live_…` (oder `x-api-key`).

### `invalid_key`

**401** · Ungültiger API-Schlüssel

**Ursache.** Der Schlüssel ist fehlerhaft aufgebaut (abgeschnittene oder neu eingetippte Kopie), unbekannt, widerrufen oder abgelaufen, oder sein Ersteller hat den Workspace verlassen. `detail` unterscheidet ein Formatproblem von einem Statusproblem.

**Was zu tun ist.** Prüfen Sie die Kopie. Ist der Schlüssel widerrufen oder abgelaufen, erstellen Sie unter Einstellungen → API und MCP einen neuen.

### `insufficient_scope`

**403** · Unzureichender Scope

**Ursache.** Dem Schlüssel fehlt ein Scope, den die Route oder das Tool verlangt. `missing_scopes` listet sie auf.

**Was zu tun ist.** Erstellen Sie einen Schlüssel mit diesen Scopes. Ein bestehender Schlüssel behält seine Scopes: Sie lassen sich nicht ändern.

### `forbidden`

**403** · Verboten

**Ursache.** Die Rolle des Schlüsselerstellers gibt keinen Zugriff auf dieses Tool oder diesen Agenten.

**Was zu tun ist.** Erstellen Sie den Schlüssel über ein Konto mit der erforderlichen Rolle (Owner oder Admin für Schreib- und Aktions-Tools und für den Agenten Onboarding).

### `not_found`

**404** · Nicht gefunden

**Ursache.** Unbekannte Route, unbekanntes Tool oder unbekannter Agent. Die interaktiven Karten des Chats (`askUser`, `proposeSources`, `proposeBoard` …) sind keine aufrufbaren Tools.

**Was zu tun ist.** Listen Sie die gültigen Namen mit `GET /api/v1/tools` und `GET /api/v1/agents` auf.

### `invalid_input`

**422** · Ungültige Eingabe

**Ursache.** Der Body ist kein gültiges JSON, oder die Eingabe passt nicht zum Schema des Tools. `issues` zeigt auf jedes fehlerhafte Feld (`path`, `message`).

**Was zu tun ist.** Vergleichen Sie Ihren Body mit dem `input_schema` des Tools (`GET /api/v1/tools/{nom}`).

### `tool_error`

**422** · Tool-Fehler

**Ursache.** Das Tool hat die Anfrage aus einem Grund abgelehnt, der Ihre Daten betrifft, zum Beispiel ein Item, das in diesem Workspace nicht existiert. `detail` nennt den Grund.

**Was zu tun ist.** Korrigieren Sie die Eingabe gemäß `detail`. Derselbe Aufruf liefert dieselbe Antwort, solange sich nichts ändert.

### `rate_limited`

**429** · Zu viele Anfragen

**Ursache.** Der Schlüssel hat sein Limit pro Minute überschritten.

**Was zu tun ist.** Warten Sie die Anzahl Sekunden aus dem Header `Retry-After` ab und versuchen Sie es erneut. Verteilen Sie Ihre Aufrufe.

### `quota_exceeded`

**429** · Tageskontingent erreicht

**Ursache.** Der Schlüssel hat sein tägliches Anfragelimit erreicht. Der Zähler wird jeden Tag um Mitternacht UTC zurückgesetzt.

**Was zu tun ist.** Versuchen Sie es nach Mitternacht UTC erneut. Um das Limit anzuheben, schreiben Sie uns über die [Kontaktseite](/contact).

### `budget_exhausted`

**402** · Monatliche Credits aufgebraucht

**Ursache.** Der Workspace des Schlüssels hat sein monatliches Credit-Limit erreicht. Alles, was Credits verbraucht (Agenten, kostenpflichtige Tools, Erfassung), wird vor dem Aufruf abgelehnt, und ein laufender Agenten-Turn stoppt, sobald er das Limit erreicht. `detail` nennt das Datum der Wiederaufnahme.

**Was zu tun ist.** Warten Sie bis zu dem in `detail` genannten Datum, oder bitten Sie einen Owner des Workspace, das Limit anzuheben.

### `plan_restricted`

**403** · Nicht im Tarif enthalten

**Ursache.** Der Tarif des Workspace des Schlüssels erlaubt diese Anfrage nicht: Er öffnet die API nicht, oder nur lesend, und die Anfrage schreibt, abonniert oder startet eine Recherche oder einen Agenten. `plan` nennt den Tarif und `api_access` den Zugriff (`none`, `read`).

**Was zu tun ist.** Bitten Sie Piqline um einen Tarif, der den benötigten Zugriff öffnet: Équipe zum Lesen, Business für vollen Zugriff.

### `unavailable`

**503** · Dienst nicht verfügbar

**Ursache.** Ein Dienst, von dem die Anfrage abhängt, antwortet nicht: Schlüsselprüfung, Agentenmodell oder Anbieter.

**Was zu tun ist.** Versuchen Sie es mit zunehmendem Abstand erneut. Hält der Fehler an, nennen Sie `request_id`, wenn Sie uns schreiben.

### `not_configured`

**503** · Nicht konfiguriert

**Ursache.** Die API ist auf dem Server nicht konfiguriert: Eine Umgebungsvariable fehlt.

**Was zu tun ist.** Nennen Sie `request_id`, wenn Sie uns schreiben: Nur Piqline kann diesen Fall beheben.

### `internal`

**500** · Interner Fehler

**Ursache.** Unerwarteter Fehler auf Seiten von Piqline. `detail` bleibt absichtlich vage.

**Was zu tun ist.** Versuchen Sie es erneut. Bleibt der Fehler bestehen, nennen Sie `request_id`, wenn Sie uns schreiben.
