Zum Inhalt springen
Hilfe-Center
Support kontaktierenApp öffnen

Fehler und Fehlercodes der API

Jede Antwort der API, die kein Erfolg ist, hat dieselbe Form.

{
"error": {
"code": "outside_call_hours",
"message": "Außerhalb der Anrufzeiten sind keine Anrufe möglich."
}
}
Feld Bedeutung
code fester Code für Ihr Programm. Bestehende Codes ändern sich nicht, neue können dazukommen.
message Meldung für Menschen, auf Deutsch. Der Wortlaut kann sich ändern.
details Zusatz je Code, nur wenn es einen gibt.

Werten Sie in Ihrem Programm code aus, nicht message. Behandeln Sie unbekannte Codes wie einen allgemeinen Fehler.

Code Status Bedeutung Was tun
unauthorized 401 Der Schlüssel fehlt, ist falsch oder widerrufen. Header Authorization: Bearer spk_live_... prüfen, sonst neuen Schlüssel anlegen.
insufficient_scope 403 Dem Schlüssel fehlt die Berechtigung. details.required_scope nennt sie. Neuen Schlüssel mit dieser Berechtigung anlegen.
invalid_request 400 Die Anfrage ist ungültig: falsches Feld, falscher Wert oder kein gültiges JSON. details.fields lesen und die Anfrage korrigieren. Nicht unverändert wiederholen.
not_found 404 Die ID oder der Pfad ist unbekannt. Auch IDs fremder Organisationen sind „nicht gefunden“. ID und Adresse prüfen.
conflict 409 Die Anfrage passt nicht zum aktuellen Zustand, zum Beispiel Abbrechen eines laufenden Anrufs oder ein schon benutzter Idempotency-Key mit anderem Body. Aktuellen Stand abfragen und danach entscheiden.
rate_limited 429 Zu viele Anfragen in einer Minute. So lange warten, wie der Header retry-after angibt, dann wiederholen.
internal_error 500 Fehler bei SpeakKI. Später wiederholen, bei POST /v1/calls mit demselben Idempotency-Key. Hält es an, schreiben Sie dem Support.
{
"error": {
"code": "invalid_request",
"message": "Ungültige Anfrage (to): Bitte geben Sie eine Zielnummer an.",
"details": {
"in": "body",
"fields": { "to": "Bitte geben Sie eine Zielnummer an." }
}
}
}

details.in nennt die Stelle: body, query, params oder header. details.fields nennt je Feld die Meldung. Unbekannte Felder führen ebenfalls zu invalid_request. Ist die Anfrage zu groß, kommt der Code mit Status 413, bei falschem Content-Type mit Status 415.

Diese Codes kommen, wenn ein Anruf oder eine Kampagne gegen eine Regel verstößt. Es entsteht dann kein Anruf. Dieselben Codes stehen in block_reason eines Anrufs mit dem Status blocked und in skip_reason eines übersprungenen Empfängers.

Code Status Bedeutung Was tun
plan_required 403 Der Tarif enthält API-Zugang oder ausgehende Anrufe nicht. Auf den Tarif Professional wechseln.
access_not_approved 403 Ausgehende Anrufe sind für die Organisation nicht freigeschaltet. Freischaltung im Dashboard unter Ausgehende Anrufe beantragen oder die Freigabe abwarten.
billing_blocked 422 Anrufe sind wegen Tarif oder Zahlung gerade nicht möglich. Tarif und Zahlung unter Einstellungen › Abrechnung prüfen.
assistant_not_found 404 Den Assistenten gibt es in Ihrer Organisation nicht. assistant_id mit GET /v1/assistants prüfen.
assistant_outbound_disabled 422 Am Assistenten sind ausgehende Anrufe nicht eingeschaltet. Am Assistenten den Abschnitt Ausgehende Anrufe einschalten.
from_number_missing 422 Am Assistenten ist keine Absendernummer hinterlegt. Absendernummer am Assistenten wählen oder from_number_id mitsenden.
from_number_not_allowed 422 Die Absendernummer ist keine eigene, aktive Rufnummer. from_number_id mit GET /v1/phone-numbers prüfen.
missing_variables 422 Für Platzhalter in Begrüßung oder Auftrag fehlen Werte. details.missing_variables nennt die Namen. Die fehlenden Werte in variables mitsenden.
Code Status Bedeutung Was tun
invalid_number 422 Die Nummer ist keine gültige Telefonnummer. Nummer in E.164 senden, zum Beispiel +4915228817386.
country_not_allowed 422 Die Nummer liegt nicht in Deutschland, Österreich oder der Schweiz. Nicht anrufen. Andere Länder sind nicht möglich.
special_number 422 Sonder- oder Mehrwertnummer. Nicht anrufen.
own_number 422 Die Nummer ist eine Ihrer eigenen Rufnummern. Andere Zielnummer wählen.
suppressed 422 Die Nummer steht auf der Sperrliste. Nicht anrufen. Die Person möchte keine Anrufe.
contact_blocked 422 Der Kontakt zu dieser Nummer ist gesperrt. Nicht anrufen oder die Sperre am Kontakt im Dashboard prüfen.
Code Status Bedeutung Was tun
outside_call_hours 422 Der Start liegt außerhalb der Anrufzeiten. Mit scheduled_at einen Zeitpunkt in den Anrufzeiten wählen oder später senden.
daily_limit_reached 422 Das Tageslimit Ihrer Organisation ist erreicht. Am nächsten Tag senden oder mit scheduled_at planen.
number_called_today 422 Für diese Nummer gibt es heute schon einen Anruf. An einem anderen Tag anrufen. Für mehrere Versuche max_attempts nutzen.

Die Werte hinter diesen Regeln stehen unter Regeln und Grenzen.

Status Wiederholen?
400, 401, 403, 404, 422 Nein. Erst die Ursache beheben.
409 Erst den aktuellen Stand abfragen.
429 Ja, nach der Wartezeit aus retry-after.
500 und Netzwerkfehler Ja, mit wachsendem Abstand. POST /v1/calls immer mit Idempotency-Key, sonst ruft Ihr Assistent vielleicht doppelt an.
async function speakki(pfad, optionen = {}) {
const response = await fetch(`https://api.speakki.de/v1${pfad}`, {
...optionen,
headers: {
Authorization: `Bearer ${process.env.SPEAKKI_API_KEY}`,
"Content-Type": "application/json",
...optionen.headers,
},
});
const body = await response.json();
if (response.ok) return body;
const { code, message, details } = body.error;
switch (code) {
case "rate_limited":
// Wartezeit in Sekunden
throw new Error(
`Bitte in ${response.headers.get("retry-after")} s wiederholen`,
);
case "missing_variables":
throw new Error(
`Es fehlen Werte: ${details.missing_variables.join(", ")}`,
);
case "suppressed":
case "contact_blocked":
// Diese Nummer nicht mehr anrufen
return null;
default:
throw new Error(`${code}: ${message}`);
}
}