Leitfäden
Fehler
Das Fehlerformat und was bei jedem Code zu tun ist.
Jeder API-Fehler ist eine Antwort application/problem+json im Format von RFC 9457:
{
"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.
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.
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.