Fehlercodes

HTTP-Statuscodes

Die itellicoAI-API verwendet standardmäßige HTTP-Statuscodes. Fehlerantworten geben JSON zurück mit:

code (maschinenlesbar)
message (menschenlesbar)
optionalem detail
optionalem errors (feldebene Validierungsprobleme)

Client-Fehler (4xx)

Status	Standard-`code`	Beschreibung	Häufige Ursachen
400	`bad_request`	Die Anfrage ist fehlerhaft oder ungültig	Ungültiges JSON, fehlerhafte Parameter, nicht unterstützte Kombinationen
401	`unauthorized`	Authentifizierung fehlt oder ist ungültig	Fehlender `X-API-Key`, widerrufener Schlüssel, abgelaufener Schlüssel
402	`payment_required`	Zugang erfordert Abrechnung/Tarifberechtigung	Funktion im aktuellen Tarif nicht verfügbar
403	`forbidden`	Authentifiziert, aber nicht berechtigt	Fehlende Berechtigung, falsches Account ausgewählt
404	`not_found`	Die angeforderte Ressource existiert nicht	Falsche UUID, gelöschte Ressource, falscher Pfad
405	`method_not_allowed`	HTTP-Methode wird nicht unterstützt	POST statt PATCH verwendet usw.
409	`conflict`	Anfrage steht im Widerspruch zum aktuellen Zustand	Doppeltes Erstellen, gleichzeitiger Aktualisierungskonflikt
410	`gone`	Ressource nicht mehr verfügbar	Entfernte/veraltete Ressource
422	`validation_error`	Anfragedaten haben Validierung nicht bestanden	Ungültige Feldwerte, Schema-Verletzungen
429	`rate_limit_exceeded`	Ein Ratenlimit wurde überschritten	Zu viele Anfragen im aktuellen Zeitfenster

Server-Fehler (5xx)

Status	Standard-`code`	Beschreibung	Was tun
500	`internal_error`	Unerwarteter Server-Fehler	Erneut versuchen. Bei anhaltenden Problemen Support mit Anfragedetails kontaktieren
502	`bad_gateway`	Fehler bei vorgelagerten Anbieter-/Diensten	Mit Backoff erneut versuchen
503	`service_unavailable`	Dienst vorübergehend nicht verfügbar	Warten und erneut versuchen
504	`gateway_timeout`	Zeitüberschreitung bei vorgelagertem Dienst	Mit Backoff erneut versuchen

Fehlerantwortformat

Alle API-Fehler folgen dieser Struktur:

{
  "code": "not_found",
  "message": "Resource not found",
  "detail": "Agent with UUID 123e4567-e89b-12d3-a456-426614174000 does not exist"
}

Validierungsfehler (422) können feldebene Details enthalten:

{
  "code": "validation_error",
  "message": "Validation failed",
  "errors": [
    {
      "field": "body.email",
      "message": "Invalid email format",
      "type": "value_error"
    },
    {
      "field": "body.name",
      "message": "Field required",
      "type": "missing"
    }
  ]
}

Häufige Probleme & Lösungen

401: API-Schlüssel funktioniert nicht

Prüfen, ob der API-Schlüssel korrekt kopiert wurde (keine Leerzeichen)
Prüfen, ob der Schlüssel unter Entwickler → API-Schlüssel widerrufen wurde
Sicherstellen, dass der richtige Header verwendet wird: X-API-Key: <dein-schlüssel>
Prüfen, ob das Schlüsselformat mit sk- beginnt
Prüfen, ob der Schlüssel zum richtigen Account gehört

403: Zugriff auf Ressource verweigert

Prüfen, ob auf eine Ressource innerhalb des eigenen Accounts zugegriffen wird
Prüfen, ob die Team-Rolle ausreichende Berechtigungen hat
Bei Subaccount-Ressourcen sicherstellen, dass das richtige Account verwendet wird

422: Validierungsfehler beim Erstellen/Aktualisieren

Prüfen, ob alle Pflichtfelder im Anfrage-Body enthalten sind
Prüfen, ob Feldwerte den erwarteten Typen entsprechen (String, Zahl, Enum)
Prüfen, ob Enum-Felder gültige Werte verwenden (siehe API-Referenz)
Sicherstellen, dass Datei-Uploads Größen- und Formatanforderungen erfüllen

429: Ratenlimit überschritten

Exponentiellen Backoff in die Integration implementieren
Anfragevolumen gegen Ratenlimits prüfen
Operationen wo möglich bündeln, um die Anfragezahl zu reduzieren
Support kontaktieren, wenn höhere Limits benötigt werden

500/503: Server-Fehler

Mit exponentiellem Backoff erneut versuchen (1 s, 2 s, 4 s, 8 s warten…)
Support auf laufende Störungen prüfen
Wenn der Fehler nach Wiederholungsversuchen anhält, Support mit den Anfragedetails kontaktieren

Gründe für Gesprächstrennungen

Wenn ein Anruf endet, zeigt die Gesprächsdetailansicht den Trennungsgrund. Diese Tabelle hilft zu verstehen, was passiert ist.

Normale Beendigungen

Grund	Beschreibung
`user_hangup`	Der Anrufer hat aufgelegt – erwartetes Verhalten
`agent_hangup`	Der KI-Agent hat den Anruf beendet (z. B. nach einer Abschlussnachricht)
`call_transfer`	Der Anruf wurde an einen anderen Agenten oder eine andere Telefonnummer weitergeleitet
`max_duration`	Der Anruf hat das konfigurierte maximale Zeitlimit erreicht
`inactivity`	Der Anruf wurde aufgrund längerer Stille beendet
`voicemail`	Mailbox wurde erkannt (ausgehende Kampagnen mit aktiviertem AMD)

Verbindungsfehler (nie verbunden)

Grund	Beschreibung
`dial_busy`	Die Nummer war besetzt
`dial_no_answer`	Niemand hat abgenommen
`dial_failed`	Wählen fehlgeschlagen – Nummernformat und Netzbetreiberstatus prüfen
`dial_rejected`	Der Empfänger hat den Anruf abgelehnt
`invalid_number`	Die Nummer ist ungültig – E.164-Format prüfen (+43720123456)

Systemfehler

Grund	Beschreibung
`network_error`	Netzwerkproblem zwischen itellicoAI und dem Netzbetreiber
`provider_error`	Der Telefonie- oder Sprachanbieter hat einen Fehler zurückgegeben
`agent_error`	Der KI-Agent hat einen internen Fehler festgestellt
`concurrency_limit`	Das gleichzeitige Anruflimit des Tarifs wurde erreicht – mit Backoff erneut versuchen oder upgraden
`unknown`	Unbekannter Fehler – support@itellico.ai mit der Gesprächs-ID kontaktieren

Gesprächsstatus

Status	Bedeutung
`active`	Anruf läuft gerade
`completed`	Anruf normal beendet
`failed`	Anruf wegen eines Fehlers fehlgeschlagen
`transferred`	Anruf an ein anderes Ziel weitergeleitet

Antwortstatus (ausgehend)

Status	Bedeutung
`waiting`	Das System ermittelt noch, wer abgenommen hat
`human`	Ein Mensch hat den Anruf entgegengenommen
`machine`	Anrufbeantworter erkannt
`user_rejected`	Empfänger hat den Anruf abgelehnt
`user_unavailable`	Keine Antwort / Zeitüberschreitung
`user_busy`	Leitung war besetzt
`unknown`	Das Annahmeergebnis konnte nicht ermittelt werden

Nächste Schritte

API-Referenz

Vollständige API-Endpunkt-Dokumentation ansehen

API-Schlüssel

API-Schlüssel erstellen und verwalten

Limits & Kontingente

Ratenlimits und Tarifkontingente ansehen

SDKs

Offizielle SDKs mit integrierter Fehlerbehandlung verwenden

Erste Schritte

Erstellen

Testen

Deploy

Verwalten

Beispiele

Fehlerbehebung

Referenz

Account-Administration

Entwickler & Integrationen

Abrechnung & Nutzung

Partner-Netzwerk

Rechtliches

Fehlercodes

HTTP-Statuscodes

Client-Fehler (4xx)

Server-Fehler (5xx)

Fehlerantwortformat

Häufige Probleme & Lösungen

Gründe für Gesprächstrennungen

Normale Beendigungen

Verbindungsfehler (nie verbunden)

Systemfehler

Gesprächsstatus

Antwortstatus (ausgehend)

Nächste Schritte

API-Referenz

API-Schlüssel

Limits & Kontingente

SDKs

​HTTP-Statuscodes

​Client-Fehler (4xx)

​Server-Fehler (5xx)

​Fehlerantwortformat

​Häufige Probleme & Lösungen

​Gründe für Gesprächstrennungen

​Normale Beendigungen

​Verbindungsfehler (nie verbunden)

​Systemfehler

​Gesprächsstatus

​Antwortstatus (ausgehend)

​Nächste Schritte

API-Referenz

API-Schlüssel

Limits & Kontingente

SDKs

HTTP-Statuscodes

Client-Fehler (4xx)

Server-Fehler (5xx)

Fehlerantwortformat

Häufige Probleme & Lösungen

Gründe für Gesprächstrennungen

Normale Beendigungen

Verbindungsfehler (nie verbunden)

Systemfehler

Gesprächsstatus

Antwortstatus (ausgehend)

Nächste Schritte