Fehler

Lehnt die Oblic API eine Anfrage ab, bezeichnet der HTTP-Status die Art des Problems. Der Antwortinhalt beschreibt es genauer: mit einem maschinenlesbaren Code und einer verständlichen Meldung, die häufig auch die nötige Handlung nennt.

Aufbau einer Fehlerantwort

Eine Ablehnung

{
  "status": "error",
  "data": null,
  "errors": [
    { "cd": "TO[0]", "message": "must be a well-formed email address" }
  ]
}
  • cd ist der Code in Großbuchstaben, nach dem Ihre Anwendung verzweigen soll: Meldungen können sich ändern.
  • errors enthält einen Eintrag je Problem. Sind zwei Felder falsch, nennt die Antwort beide.
  • Eine Ablehnung vor der Routenausführung, wegen des Schlüssels, seiner Adresse, seiner Berechtigungen oder des angegebenen Unterkontos, lässt data weg. Eine Antwort mit 204 hat überhaupt keinen Inhalt.

Statuscodes

StatusBedeutung
200, 201, 202, 204Erledigt; erstellt; zum Senden oder erneuten Zustellen eingereiht; erledigt ohne Antwortinhalt
400Die Anfrage ist in dieser Form ungültig: ein Feld, ein Parameter oder der Inhalt
401Der Schlüssel fehlt oder ist Oblic unbekannt. Siehe Authentifizierung
402INSUFFICIENT_BALANCE: Eine Marketing-SMS oder WhatsApp-Nachricht trifft auf eine leere Geldbörse des zahlenden Kontos. Anmeldecodes, Transaktionsnachrichten und Antworten werden weiterhin gesendet
403Adresse, Berechtigungen oder Rolle des Schlüssels erlauben die Aktion nicht, oder das Konto darf sie nicht ausführen, etwa ein Unterkonto, das Unterkonten erstellt
404Die Route existiert nicht oder das Konto hat keine solche Ressource
405, 415Die Route akzeptiert die Methode nicht und nennt erlaubte Methoden im Header Allow, oder sie akzeptiert den Inhaltstyp nicht: Senden Sie application/json
409Ein Konflikt mit vorhandenen Daten: ein für eine andere Nachricht verwendeter Idempotency-Key oder eine bereits vorhandene Vorlage
413MESSAGE_TOO_LARGE: Die Nachricht ist zum Senden zu groß
422Die Anfrage wurde verstanden, kann aber nicht wie verlangt ausgeführt werden: unverifizierter Absender, nicht genehmigte Vorlage oder abgemeldete Nummer
429Ein Limit ist erreicht; der Header Retry-After nennt die Wartezeit in Sekunden
500In Oblic ist ein Fehler aufgetreten
502Meta hat einen Schritt beim Verbinden einer WhatsApp-Nummer abgelehnt
503Ein von Oblic benötigter Dienst ist gerade nicht verfügbar; nichts wurde ausgeführt

Jede Seite nennt die Codes ihrer Routen, etwa Nachrichten und Webhooks.

Validierungsfehler

  • Ein fehlendes oder ungültiges Feld im Anfrageinhalt wird mit seinem Pfad in Großbuchstaben als cd zurückgegeben, beispielsweise TO, TO[0], FROMNAME oder ATTACHMENTS[0].FILENAME. Die verletzte Regel steht in message. Eine Ausnahme ist das Hinzufügen von Kontakten zu einer Liste: Ein ungültiger Kontakt ergibt wie ein Parameter BAD_REQUEST (siehe Kontaktlisten).
  • Ein ungültiger Abfrage- oder Pfadparameter, etwa ein limit von 500 oder ein ungültiger cursor, ergibt BAD_REQUEST. message nennt den Parameter: „limit ist ungültig.“
  • Ein fehlender Inhalt oder ein Inhalt, der kein JSON ist, ergibt BAD_REQUEST: „Der Anfrageinhalt fehlt oder ist kein gültiges JSON für diese Route.“
  • Eine nicht vorhandene Route ergibt 404 NOT_FOUND: „Diese Route existiert nicht.“
  • Ein der Route unbekanntes Feld wird ignoriert.

Erneute Versuche

  • Versuchen Sie es später erneut bei 429, nach den in Retry-After genannten Sekunden, sowie bei 500, 503 oder ausbleibender Antwort mit zunehmenden Wartezeiten. Verwenden Sie bei jedem erneuten Sendeversuch denselben Idempotency-Key, damit nur einmal gesendet wird. Siehe Nachrichten.
  • Ändern Sie zuerst etwas bei allen anderen 4xx-Antworten: Dieselbe Anfrage wird erneut abgelehnt. Laden Sie bei 402 die Geldbörse auf. Die Ausnahme ist 422 OUTSIDE_PROMOTIONAL_HOURS, ebenfalls mit Retry-After: Dieselbe SMS wird gesendet, sobald das zulässige Zeitfenster beginnt.
War diese Seite hilfreich?