HilfezentrumIntegrationen

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"}
  }
}
FeldWas es enthält
codeDer Statuscode wieder.
messageDer 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_typeDie 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.
reasonWeitere Details, wenn es welche gibt: Die IDs der abweichenden Aufzeichnungen, oder das Problem im ersten Feld. Oft sind diese Felder leer.
errorsFü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:

messageWas ist falsch?
FieldRequiredExceptionEs fehlt – oder es ist ein leerer Platz, an dem nichts sein kann.
FieldValidatorFailedExceptionSeine 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, FieldMaxLengthExceptionEs ist entweder zu kurz oder zu lang.
FieldLimitTooLargeExceptionEine 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, FieldPhoneTypeExceptionNicht eine E-Mail-Adresse, und auch kein Telefonnummer inklusive Landeskode.
FieldNameTypeExceptionEin Name, der die Zeichen nicht halten kann…
FieldPathSlugTypeExceptionEine Tag-ID oder Reference-ID, die aus Zeichen besteht, die keine Buchstaben, Zahlen, Bindestriche oder Schlaufen sind.
FieldDateTypeExceptionKeine 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

StatusWas es bedeutetWas zu tun
400Die 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.
401Der Schlüssel selbst wurde abgelehnt. Siehe dazu Authentifizierung von API-Anfragen mit einem Schlüssel.Halt und überprüfe den Schlüssel.
403Die 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.
404Das 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.
500InternalError: 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.
503TransientException: 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. Und CaseUserLimitOrTransactionException wird 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.

Verwandte Artikel

Authentifizieren Sie API-Anfragen mit einem SchlüsselSenden Sie Ihren Schlüssel als Bearer-Token an die API des Admin-Panels für einen Verwaltungsschlüssel oder an die API des Portals für einen Hub-Schlüssel und beschränken Sie ihn auf Ihre IP-Adressen.IntegrationenVerstehen Sie, was die API leisten kann.Erfahren Sie, welche Funktionen eine Verwaltungstaste und eine Hub-Taste jeweils haben, warum jede Taste als virtueller Assistent fungiert und wo Sie die vollständige technische Auflistung finden.Integrationen