Für: Administratoren
API-Fehler und Statuscodes behandeln
Lesen Sie den Fehlertext, was 400, 401, 403, 404, 500 und 503 bedeuten und warum ein Element, dessen Schlüssel nicht angezeigt werden kann, 404.
In diesem Artikel5 Abschnitte
Diese Seite beschreibt, wie beide APIs eine abgewiesene Anrufe melden – sowohl bei der Verwendung einer „Manage-Key“ als auch bei der Verwendung einer „Hub-Key“.
Der Fehlertext
Jeder abgewiesene Anruf liefert einen Statuscode sowie ein JSON-Datenobjekt zurück.
{
"error": {
"code": 400,
"message": "CaseReferenceIdExistsException",
"error_type": "ClientException",
"reason": {"case_id": "cc-1a2b3c4d5e6f70", "host_id": "ca-7e6d5c4b3a2f10"}
}
}
| Feld | Was es enthält |
|---|---|
code | Der Statuscode wieder. |
message | Der Name des Fehlers ist beispielsweise CaseReferenceIdExistsException. Lassen Sie Ihren Code auf diesen Fehler reagieren – dieser Name bleibt unverändert, unabhängig vom Sprachcode des Lesers. |
error_type | Die Art der Fehler: ClientException für eine Ablehnung, ApiException für einen ungültigen Antrag, SessionException für einen fehlenden Schlüssel, ModelException für einen abgelehnten Schlüssel oder eine Ablehnung seitens des Datenbestands, TransientException für ein Problem, das durch Wiederholung des Vorgangs gelöst werden kann, InternalError für ein Fehlerbild in CaseActive. |
reason | Weitere Details, wenn es welche gibt: Die IDs der abweichenden Aufzeichnungen, oder das Problem im ersten Feld. Oft sind diese Felder leer. |
errors | Für eine ungültige Anfrage wird pro Feld nur ein Eintrag verwendet. |
Feldfehler
Ein Antrag, bei dem ein oder mehrere Felder fehlen oder ungültig sind, erhält die Antwort 400 SchemaFieldsException. Für jedes fehlende oder ungültige Feld gibt es eine Eintragung mit dem Feldnamen errors. Das Feld location wird durch Punkte dargestellt – ein Feld befindet sich also innerhalb eines anderen Feldes. Das Problem wird mit message angegeben.
{
"error": {
"code": 400,
"message": "SchemaFieldsException",
"error_type": "ApiException",
"reason": "FieldRequiredException",
"errors": [
{"domain": "json", "location": "ref_id", "locationId": "ref_id", "locationType": "schema", "message": "FieldRequiredException", "reason": "FieldRequiredException"}
]
}
}
domain ist json für den Körper und query für die Parameter der Adresse. Häufige Fehler bei den Feldern:
message | Was ist falsch? |
|---|---|
FieldRequiredException | Es fehlt – oder es ist ein leerer Platz, an dem nichts sein kann. |
FieldValidatorFailedException | Seine Wertigkeit ist nicht zulässig – beispielsweise kann es sich um eine Rolle, einen Falltyp oder eine Phase handeln, die in Ihrem Hub nicht vorhanden sind. |
FieldMinLengthException, FieldMaxLengthException | Es ist entweder zu kurz oder zu lang. |
FieldLimitTooLargeException | Eine Liste… limit Es handelt sich um eine Seite, auf der mehr als 1000 Elemente angezeigt werden können. Das ist die maximale Anzahl an Elementen, die auf einer Seite dargestellt werden können. |
FieldEmailTypeException, FieldPhoneTypeException | Nicht eine E-Mail-Adresse, und auch kein Telefonnummer inklusive Landeskode. |
FieldNameTypeException | Ein Name, der die Zeichen nicht halten kann… |
FieldPathSlugTypeException | Eine Tag-ID oder Reference-ID, die aus Zeichen besteht, die keine Buchstaben, Zahlen, Bindestriche oder Schlaufen sind. |
FieldDateTypeException | Keine Datumsangaben, wie zum Beispiel 2026-03-15 |
Die von der API nicht erkannten Felder werden einfach ignoriert – sie werden nicht abgelehnt. Bitte überprüfen Sie daher Ihre Schreibweise gegen die Referenzwerte.
Statuscodes
| Status | Was es bedeutet | Was zu tun |
|---|---|---|
| 400 | Die Anfrage ist ungültig oder die Änderung ist nicht möglich. Es handelt sich dabei um ein Feldfehler oder eine Ablehnung, wie in message angegeben – beispielsweise CaseReferenceIdExistsException. | Bearbeiten Sie den Text, bevor Sie ihn erneut senden. |
| 401 | Der Schlüssel selbst wurde abgelehnt. Siehe dazu Authentifizierung von API-Anfragen mit einem Schlüssel. | Halt und überprüfe den Schlüssel. |
| 403 | Die Schlüssel können diese Aufgabe nicht erfüllen: Eine Anrufaktion kann den Schlüssel nicht verwenden (BotNotAllowedException); ein gesperrter Hub (ManageBillingInactiveException für einen Schlüssel, BillingReadOnlyException für einen Hub-Schlüssel, sobald das Portal nur noch als Lesebereich verwendet wird); ein geschlossener Fall (CaseClosedException); oder eine Änderung, die mit einer anderen Änderung gleichzeitig stattfindet (ItemUpdateFailedException und andere). | Beheben Sie die Ursache des Problems. Falls es zu einem Konflikt kommt, lesen Sie den entsprechenden Text noch einmal durch – anschließend versuchen Sie es erneut. |
| 404 | Das Produkt existiert nicht. Es gehört zu einem anderen Hub. Das Produkt wird gelöscht. Oder Ihre Schlüssel können das Produkt nicht erkennen. | Prüfen Sie die Identifikationsnummer. |
| 500 | InternalError: Ein Fehler in CaseActive. Die Entwickler von CaseActive werden darüber informiert. | Versuchen Sie es später noch einmal. Wenn das Problem weiterhin besteht, wenden Sie sich an den Support. |
| 503 | TransientException: Der Hub war für einen Moment zu beschäftigt. | Warten Sie eine kurze Zeit ab – je öfter man wartet, desto länger dauert das Warten. |
Ein Anruf, der länger als 30 Sekunden dauert, wird von der Netzwerkseite mit einer 504-Fehlermeldung abgebrochen – ohne dass ein JSON-Body übermittelt wird. Importen vermeiden dieses Problem, indem sie im Hintergrund ausgeführt werden.
Warum ein Artikel, von dem Sie wissen, dass er existiert, beantwortet den Fehler 404
Ein Hub-Key funktioniert als „Hub“ für Ihr System. Virtuelle Assistentin/Virtueller AssistentVirtueller Assistent Ein automatisiertes Teammitglied, das Begrüßungsnachrichten, Check-ins und Statusmeldungen für das Unternehmen veröffentlicht; seine Beiträge sind mit einem Virtual Assistant-Abzeichen versehen., Und es wird nur das angezeigt, was die Rolle des virtuellen Assistenten sehen kann. Ein Element, das von dieser Rolle verborgen bleibt, erzeugt eine Fehlermeldung mit der Nummer 404 – genauso wie ein Element, das gar nicht existiert. Deshalb zeigt die API dieses Element nicht an. Auch bei der Bearbeitung oder Löschung einer veröffentlichten Rechnung oder eines veröffentlichten elektronischen Dokuments, die von dieser Rolle nicht gesehen werden können, wird weiterhin eine Fehlermeldung mit der Nummer 403 angezeigt. PublishAlreadyPublishedException. Listen lassen solche Dinge einfach weg – ohne dass es erwähnt wird. Um zu erfahren, welche Möglichkeiten diese Funktion bietet, lesen Sie weiter. role::bots Mit einer Verwaltungsschlüssel – siehe dazu… Lesen der Rollen mit dem Management-Key.
Sie können es bedenkenlos erneut versuchen.
- 503 – und alle
TransientException-Werte nach einer kurzen Wartezeit. - 400
TransactionCanceledException– das ist eine Situation, die durch einen hektischen Moment entsteht. UndCaseUserLimitOrTransactionExceptionwird dann nicht mehr voll sein, sobald man den Fall überprüft hat. - 500 – etwas später.
Versuchen Sie nicht erneut, die anderen 400-Statuscodes zu senden – ein 401-, 403- oder 404-Statuscode bleibt unverändert. Diese werden wieder abgelehnt.