# Wenn eine API-Anfrage scheitert

> Statuscode und Meldung einordnen und die Ursache bei Schlüssel, Rechten, Eingabe oder Limit finden.

Quelle: https://support.unitedsynergy.com/api/fehlerbehebung/

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](https://support.unitedsynergy.com/api/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](https://support.unitedsynergy.com/api/app-tools/#anfragelimits).

## Der Katalog ist leer oder ein Tool fehlt

Ein Tool, das in der [Referenz nach App](https://support.unitedsynergy.com/api/referenz/) 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.