Fehlercodes der API
Jeder Fehlercode der Outbound-API mit HTTP-Status, Bedeutung und Lösung, damit deine Integration richtig reagiert.
Lehnt die Outbound-API eine Anfrage ab, antwortet sie mit success: false, einem festen Code in error und einer Erklärung in message. Deine Integration verzweigt auf error, nicht auf den Text: die Codes bleiben stabil, Texte können sich ändern.
{
"success": false,
"error": "invalid_to_number",
"message": "toNumber must be an international number in E.164 format …"
}
Übersicht
| Status | Bedeutung | Erneut versuchen? |
|---|---|---|
| 400 | Die Anfrage ist unvollständig oder ungültig | erst nach Korrektur |
| 401 | Anmeldung fehlt oder ist ungültig | erst nach Korrektur |
| 402 | Abo oder Zahlung fehlt für diesen Weg | erst nach Zahlung |
| 403 | Diese Aktion ist für dein Konto oder die Nummer noch nicht freigegeben | erst nach Freigabe |
| 409 | Eine Anfrage mit demselben Idempotency-Key läuft noch | ja, nach Retry-After |
| 422 | Die Anfrage passt nicht zur Konfiguration | erst nach Korrektur |
| 429 | Grenze erreicht | ja, nach Retry-After |
| 500, 503 | Fehler auf unserer Seite | ja, mit Abstand, und mit demselben Idempotency-Key |
400: Anfrage ungültig
invalid_to_number
Die Zielnummer ist nicht im Format E.164. Schreib sie mit Pluszeichen und Ländervorwahl, etwa +491701234567. Nationale Formen wie 0170 … weist die API ab, weil sich daraus das Land nicht sicher ergibt.
invalid_from_number
Die Absendernummer ist nicht im Format E.164. Schreib sie wie die Zielnummer mit Pluszeichen und Ländervorwahl.
outbound_number_required
fromNumber fehlt. Gib deine Absendernummer an: eine importierte oder per SIP verbundene Nummer, der ein Agent zugewiesen ist.
platform_number_inbound_only
Die Absendernummer ist eine bei bhomy gekaufte Nummer. Diese nehmen nur Anrufe an. Importiere deine eigene Nummer oder verbinde sie per SIP.
invalid_idempotency_key
Der Header Idempotency-Key ist leer, länger als 255 Zeichen oder enthält Zeichen außerhalb von ASCII. Nutze etwa eine UUID.
validation_error
Die Absendernummer ließ sich gerade nicht prüfen. Versuch es mit Abstand erneut.
Fehlt der Body oder ist er kein gültiges JSON, antwortet die API ebenfalls mit 400, dann mit einer Erklärung in error, etwa „Missing required field: toNumber“.
401: Anmeldung
Bei 401 steht der Grund in code:
code | Lösung |
|---|---|
auth.missing_header | Schick den Header Authorization: Bearer … mit |
auth.invalid_type | Der Header beginnt mit Bearer und einem Leerzeichen |
auth.invalid_key | Den Schlüssel gibt es nicht. Prüfe ihn auf Leerzeichen und Zeilenumbrüche |
auth.key_revoked | Der Schlüssel ist deaktiviert. Reaktiviere ihn unter API Key oder nutze einen anderen |
Mehr dazu unter API-Schlüssel.
402: Zahlung
imported_number_subscription
Anrufe von einer importierten Nummer brauchen ein laufendes Abo ohne offene Rechnung. Begleiche offene Rechnungen unter Abrechnung.
403: noch nicht freigegeben
identity_not_verified
Über die API ruft bhomy erst an, wenn deine Identität bestätigt ist. Die Antwort enthält verify_url, den Link zur Karte Identität unter Abrechnung. Die Prüfung machst du einmal, siehe Ausgehende Anrufe.
sender_not_verified
Die Absendernummer ist noch nicht für ausgehende Anrufe bestätigt. Bestätige sie mit dem Prüfanruf in ihren Einstellungen unter Telefonnummer.
outbound_disabled
Für diese SIP-Nummer sind ausgehende Anrufe nicht eingerichtet. Verbinde sie mit Termination-Adresse und Zugangsdaten deines Anbieters.
409: läuft noch
idempotency_request_in_progress
Eine Anfrage mit demselben Idempotency-Key wird gerade bearbeitet. Warte die Sekunden aus Retry-After ab und schick dieselbe Anfrage erneut. Du bekommst dann die Antwort der ersten.
422: passt nicht zur Konfiguration
idempotency_key_reused
Dieser Idempotency-Key gehört schon zu einer anderen Anfrage. Nutze für jeden neuen Anruf einen neuen Schlüssel.
no_assistant_mapped
Der Absendernummer ist kein Agent zugewiesen. Weise ihr unter Telefonnummer einen Agenten zu.
imported_number_destination
Eine importierte Nummer ruft deutsche Festnetz- und Mobilfunknummern an. Für andere Ziele nutzt du eine SIP-Nummer über deinen eigenen Anbieter.
429: Grenze erreicht
rate_limit_exceeded
Mehr als 60 Anfragen in 60 Sekunden. limit_scope nennt die Grenze: je IP-Adresse oder je API-Schlüssel. Warte die Sekunden aus Retry-After ab und verteile deine Anfragen.
concurrent_limit_reached
Alle Leitungen sind belegt. Mit limit_scope: "account" sind es die gleichzeitigen Anrufe deines Tarifs, die Antwort nennt dann current und limit. Mit limit_scope: "platform" hält bhomy kurz Leitungen für eingehende Anrufe frei. Warte in beiden Fällen die Sekunden aus Retry-After ab.
500 und 503: Fehler auf unserer Seite
outbound_not_configured
Ausgehende Anrufe sind auf unserer Seite gerade nicht eingerichtet. Melde dich beim Support.
outbound_unavailable
Der Dienst für ausgehende Anrufe ist vorübergehend nicht erreichbar. Versuch es nach einigen Minuten erneut.
dispatch_failed
Der Agent konnte nicht losgeschickt werden. Versuch es mit demselben Idempotency-Key erneut, dann entsteht kein doppelter Anruf.
internal_error
Ein unerwarteter Fehler. Versuch es erneut. Bleibt der Fehler, schreib uns.
Bei diesen Fehlern enthält die Antwort oft error_id. Schick sie uns mit, siehe Problem melden. Damit finden wir den Vorgang sofort.
Wenn der Auftrag angenommen wurde, aber kein Gespräch zustande kam
Eine Antwort 202 heißt: der Auftrag ist angenommen. Was danach passiert, steht als Ergebnis am Anruf im Anrufverlauf, etwa Nicht abgenommen, Mailbox oder Gesperrt, wenn dein Konto gesperrt war. Die Ergebnisse erklärt Kampagnen.
War diese Seite hilfreich?