Jede abgewiesene Anfrage nennt einen Statuscode und eine Meldung. Bei den meisten Fehlern steht die Meldung im Feld message, bei 422 im Feld error. Die Tabellen zeigen, womit die Meldung beginnt, was dahintersteckt und was du tun kannst.
401: Der Schlüssel wird nicht akzeptiert
| Meldung beginnt mit | Ursache | Lösung |
|---|---|---|
Nicht eingeloggt | Der Header X-API-KEY fehlt. | Header mitsenden und Schreibweise prüfen. |
Ungueltiger oder fehlender API-Key | Der Schlüssel ist falsch kopiert, unbekannt oder wurde widerrufen. | Schlüssel neu aus dem Secret Store einsetzen. Wurde er widerrufen, einen neuen beantragen. |
403: Der Schlüssel ist gültig, aber etwas fehlt
| Meldung beginnt mit | Ursache | Lösung |
|---|---|---|
API-Key fehlt Scope: app-tools | Der Schlüssel wurde für eine andere Anbindung ausgegeben. | Einen App-Tools-Key beantragen, siehe API-Keys. |
API-Key hat keinen Actor-User | Dem Schlüssel ist kein technischer Benutzer zugeordnet. | Neuen Schlüssel mit Actor-User ausgeben lassen. |
Actor-User des API-Keys existiert nicht mehr | Der technische Benutzer wurde gelöscht. | Benutzer neu anlegen und dafür einen neuen Schlüssel ausgeben lassen. |
Modul … ist nicht aktiv | Die App ist im Mandanten nicht aktiviert. | App aktivieren lassen oder ein Tool einer aktiven App nutzen. |
Permission fehlt: … | Der Rolle des Actor-Users fehlt das genannte Recht, zum Beispiel update:Konto. | Das Recht in der Rolle ergänzen, aber nur so weit wie nötig. |
400, 404, 422 und 501: Anfrage oder Tool passt nicht
| Status und Meldung | Ursache | Lösung |
|---|---|---|
400 Tool-Name fehlt | Im Body fehlt name, oder der Body ist kein gültiges JSON. | JSON-Body mit name senden und Content-Type: application/json setzen. |
400 mit anderer Meldung | Die Eingabe verletzt das inputSchema. Mehrere Verstöße stehen mit Semikolon getrennt in einer Meldung. | Eingabe nach dem Schema aus dem aktuellen Katalog korrigieren. |
404 Tool nicht gefunden: … | Der Tool-Name ist falsch geschrieben oder existiert in dieser Version nicht. | Namen exakt aus dem aktuellen Katalog übernehmen. |
422 mit ok: false | Das Tool lief, konnte die fachliche Aktion aber nicht ausführen, zum Beispiel weil ein Datensatz fehlt. | Zustand mit einem Lese-Tool prüfen, nicht blind wiederholen. |
422 mit Datenbankcode … | Die Datenbank hat die Änderung abgelehnt, etwa 23505 für einen Wert, der eindeutig sein muss und schon existiert, oder 23503 für einen fehlenden verknüpften Datensatz. | Eingabe anhand des Satzes vor dem Code korrigieren. Interna wie Tabellennamen nennt die Antwort bewusst nicht. |
501 Kein Handler registriert | Das Tool ist bekannt, aber auf dem Server fehlt die Umsetzung. | Support mit Tool-Name und Zeitpunkt informieren. |
429: Zu viele Anfragen
| Meldung | Ursache | Lösung |
|---|---|---|
Zu viele Anfragen | Das Limit für diesen Schlüssel ist im aktuellen Zeitfenster erreicht. | Die Sekunden aus Retry-After abwarten, Last über die Zeit verteilen. |
Die Limits stehen in der Referenz unter Anfragelimits.
Der Katalog ist leer oder ein Tool fehlt
Ein Tool, das in der Referenz nach App steht, fehlt in deinem Katalog, wenn die App im Mandanten nicht aktiv ist oder dem Actor-User das Recht fehlt. Ruf den Katalog mit includeStructure=1 ab: structure zeigt die sichtbaren Apps und die effektiven Rechte des Actor-Users.
Was der Support braucht
Nenne Instanz, Zeitpunkt, Statuscode, Meldung, Tool-Name und das Präfix des Schlüssels. Schick nie den vollständigen API-Key und keine personenbezogenen Antwortdaten.