API-Fehler beheben
Diese Anleitung erklärt die häufigsten Fehler bei der API-Integration — aus Nutzersicht, ohne interne Details. Sie folgt dem Muster: Symptom → Erklärung → Lösung.
Was Sie erreichen werden
- 404-Fehler durch falschen Organisationsscope erkennen und beheben
- Race Conditions zwischen Webhook und API-Abruf verstehen
- 5xx-Fehler mit Retry-Strategie und Backoff abfangen
- 401- und 405-Fehler schnell eingrenzen
- Wissen, wann ein einzelnes Support-Ticket sinnvoll ist
Voraussetzungen
- Grundkenntnisse der API-Einführung
Symptom: 404 — Ressource nicht gefunden
Erklärung: falscher Organisationsscope
Ein 404 Not Found bedeutet in der dalvon API nicht zwangsläufig, dass die Ressource nicht existiert — sie kann schlicht im Scope des verwendeten API-Schlüssels nicht sichtbar sein.
Jeder API-Schlüssel ist an genau eine Organisation gebunden. Rufen Sie eine Ressource ab, die einer anderen Organisation gehört, erhalten Sie 404 (und nicht 403). Das ist kein Fehler in Ihrem Code, sondern ein Scope-Problem.
Typische Situation: Sie empfangen per Webhook eine Anruf-ID und rufen anschließend GET /calls/<id> ab — aber der API-Schlüssel gehört zu einer anderen Organisation als der Anruf. Ergebnis: 404.
Lösung:
- Prüfen Sie, welcher Organisation Ihr API-Schlüssel zugeordnet ist: Rufen Sie
GET /agents/auf und gleichen Sie die zurückgegebenen Agenten mit dem Dashboard ab - Stellen Sie sicher, dass Sie den API-Schlüssel der Organisation verwenden, in der der Anruf stattgefunden hat
- Wenn Sie Ressourcen mehrerer Organisationen abrufen, benötigen Sie pro Organisation einen eigenen Schlüssel
Erklärung: 404 direkt nach einem Webhook (Race Condition)
Wenn Sie unmittelbar nach Empfang eines Webhooks die darin enthaltene Anruf-ID per API abrufen, kann es zu einer kurzen Verzögerung kommen, bis der Anruf vollständig in der API verfügbar ist.
Lösung:
- Warten Sie nach Empfang des Webhooks einige Sekunden, bevor Sie den API-Abruf starten
- Oder: Lesen Sie die Anruf-Daten direkt aus dem Webhook-Payload — dieser enthält bereits alle relevanten Felder (Transkript, Zusammenfassung, Dauer)
# Beispiel: Kurze Wartezeit vor dem API-Abruf
sleep 3
curl -X GET "https://api.dalvon.ai/calls/CALL_ID" \
-H "Authorization: Bearer IHR_API_KEY"
Erklärung: 404 bei falscher URL oder falschem Endpunkt
Prüfen Sie die Basis-URL und den Pfad:
- Korrekte Basis-URL:
https://api.dalvon.ai - Pfade enden ohne abschließenden Slash bei Einzel-Ressourcen:
GET /agents/AGENT_ID - Pfade enden mit Slash bei Listen:
GET /agents/
Symptom: 401 — Nicht authentifiziert
Erklärung: Der API-Schlüssel fehlt, ist abgelaufen oder falsch übermittelt.
Lösung:
| Prüfpunkt | Was tun |
|---|---|
| Header-Format | Muss exakt lauten: Authorization: Bearer IHR_KEY — kein extra Leerzeichen, kein Token-Prefix |
| Schlüssel aktiv | Im Dashboard unter Einstellungen → API-Schlüssel prüfen, ob der Schlüssel noch vorhanden ist |
| Schlüssel rotiert | Falls jemand den alten Schlüssel gelöscht hat, einen neuen erstellen und im System hinterlegen |
Symptom: 405 — Methode nicht erlaubt
Erklärung: Der Endpunkt existiert, akzeptiert aber nicht die verwendete HTTP-Methode.
Typische Ursache: Ein DELETE-Endpunkt erwartet die Ressourcen-ID als Query-Parameter, nicht im Pfad — oder umgekehrt.
Lösung: Prüfen Sie in der API-Referenz, welche Methode der Endpunkt erwartet, und ob die ID im Pfad oder als Query-Parameter übergeben werden muss.
Beispiel für einen häufigen Fehler:
# Falsch — ID im Pfad, aber Endpunkt erwartet Query-Parameter
DELETE /contacts/CONTACT_ID
# Richtig
DELETE /contacts/?contact_id=CONTACT_ID
Symptom: 422 — Validierungsfehler
Erklärung: Die Anfrage ist syntaktisch korrekt, aber ein Feld hat einen ungültigen Wert oder ein Pflichtfeld fehlt.
Lösung: Lesen Sie das detail-Array in der Fehlermeldung — es nennt das genaue Feld und den Fehlertyp:
{
"detail": [
{
"loc": ["body", "phone_number"],
"msg": "Ungültiges Nummernformat",
"type": "value_error"
}
]
}
Häufige Ursachen:
- Telefonnummer nicht im internationalen Format (
+491234567890statt0049...oder01234...) first_nameundlast_namegetrennt angeben — die API kennt kein kombiniertesname-Feld- Enum-Wert (z.B.
contact_type) entspricht nicht den erlaubten Werten
Symptom: 5xx — Serverseitiger Fehler
Erklärung: 500 Internal Server Error, 503 Service Temporarily Unavailable und ähnliche Codes zeigen einen vorübergehenden Fehler auf Serverseite — nicht in Ihrem Code.
Lösung: Retry mit exponentiellem Backoff
Wiederholen Sie die Anfrage nicht sofort, sondern mit zunehmenden Wartezeiten:
import time
import requests
def api_request_with_retry(url, headers, max_retries=3):
delay = 2 # Sekunden Wartezeit beim ersten Versuch
for attempt in range(max_retries + 1):
response = requests.get(url, headers=headers)
if response.status_code < 500:
return response # Erfolg oder Client-Fehler — nicht wiederholen
if attempt < max_retries:
print(f"Versuch {attempt + 1} fehlgeschlagen ({response.status_code}), warte {delay}s...")
time.sleep(delay)
delay *= 2 # Exponentieller Backoff: 2s → 4s → 8s
return response # Letztes Ergebnis zurückgeben
# Einfaches Shell-Beispiel mit Wartezeit
for i in 1 2 3; do
STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
-H "Authorization: Bearer IHR_API_KEY" \
"https://api.dalvon.ai/calls/CALL_ID")
[ "$STATUS" -lt 500 ] && break
echo "Versuch $i fehlgeschlagen ($STATUS), warte..."
sleep $((2 ** i))
done
Hinweis: Senden Sie bei einem 5xx-Fehler kein sofortiges Support-Ticket — vorübergehende Fehler lösen sich in den meisten Fällen durch eine Wiederholung von selbst. Öffnen Sie ein Ticket nur, wenn der Fehler nach mehreren Versuchen über einen längeren Zeitraum anhält.
Wiederholte oder anhaltende Fehler melden
Falls ein Fehler nach mehreren Retry-Versuchen über mehr als 10 Minuten anhält, wenden Sie sich an den Support. Für eine schnelle Lösung helfen folgende Angaben:
| Information | Wo Sie sie finden |
|---|---|
| Anruf-ID | Im Dashboard unter Anrufe → Anruf auswählen → Detail-Ansicht |
| Endpunkt und HTTP-Methode | Ihre Integration / Logs |
| HTTP-Statuscode | Antwort der API |
Fehlermeldung (detail) | Body der Fehlerantwort |
| Uhrzeit des Fehlers | Ihre Logs |
Bitte senden Sie pro Problem ein Ticket — mehrere Tickets zum selben Fehler verlangsamen die Bearbeitung.
- E-Mail: support@dalvon.ai
- Chat: Im Dashboard unten rechts
Nächste Schritte
- API-Einführung - Grundlagen, Authentifizierung und Statuscodes
- Webhooks - Anrufdaten direkt empfangen statt abzufragen