Was sind die Limits und Fehlermeldungen der API?

Wie viele Anfragen dürfen Sie stellen?

Die API begrenzt die Anzahl der Anfragen pro Minute und Konto.

Kontotyp	Anfragen pro Minute
Kostenlos	30
Bezahlt	120

Überschreiten Sie dieses Limit, erhalten Sie den Statuscode 429 sowie einen Header, der angibt, wie lange Sie warten müssen:

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{
  "error": {
    "type": "invalid_request",
    "message": "Rate limit exceeded, try again after 60 seconds"
  }
}

Solange alles reibungslos läuft, gibt es keine Header, die Ihren Verbrauch protokollieren. Beachten Sie daher den Wert von Retry-After und behalten Sie selbst im Blick, wie viele Anfragen Sie senden. Zwischenspeichern (cachen) Sie außerdem Daten, die sich selten ändern: Die Felder einer Liste müssen Sie nicht bei jedem Seitenaufruf neu abrufen, einmal pro Tag reicht völlig aus.

Wie sieht eine Fehlermeldung aus?

Alle Fehlermeldungen sind gleich aufgebaut, sodass Sie diese zentral an einer Stelle abfangen können. Jeder Fehler wird als JSON zurückgegeben und enthält ein type, ein message sowie meistens einen code und den parameter, der den Fehler verursacht hat.

{
  "error": {
    "type": "invalid_input",
    "message": "Email: invalid address",
    "code": 208,
    "parameter": "email"
  }
}

Das Feld type kann drei Werte annehmen: invalid_request, wenn der Aufruf selbst fehlerhaft ist, invalid_input, wenn die übermittelten Daten nicht stimmen, und internal, wenn aufseiten von Laposta ein Fehler auftritt.

Statuscodes

Die API verwendet reguläre HTTP-Statuscodes, um anzugeben, wie die Anfrage verlaufen ist.

Code	Bedeutung
`200`	Erfolgreich.
`201`	Erfolgreich, und es wurde etwas erstellt.
`400`	Etwas stimmt nicht mit der Anfrage oder den übermittelten Daten.
`401`	Kein gültiger Schlüssel übermittelt oder dieser Endpoint ist für dieses Konto nicht aktiviert.
`402`	Die Daten waren korrekt, aber die Anfrage wurde nicht ausgeführt.
`404`	Dieser Pfad existiert nicht.
`429`	Zu viele Anfragen innerhalb einer Minute.
`500`	Aufseiten von Laposta ist ein Fehler aufgetreten.

Ein nicht existierendes Objekt liefert keinen 404-, sondern einen 400-Statuscode mit dem Fehlercode 203. Prüfen Sie daher nicht auf 404, um festzustellen, ob eine Liste oder ein Abonnent existiert, da Sie diesen Code nur bei einem nicht existierenden Pfad erhalten.

Fehlercodes

Bei invalid_input wird ein numerischer Code mitgeliefert, sodass Sie den Fehler in eine verständliche Nachricht für Ihre eigenen Benutzer übersetzen können. Zusammen mit parameter wissen Sie genau, um welches Feld es sich handelt.

Code	Bedeutung
`201`	Der Parameter ist leer.
`202`	Der angegebene Wert hat nicht das richtige Format.
`203`	Der angegebene Wert existiert nicht, zum Beispiel eine ID, die nicht zu diesem Konto gehört.
`204`	Der Wert existiert bereits.
`205`	Der Wert ist keine Zahl.
`206`	Der Wert ist nicht `true` oder `false`.
`207`	Der Wert ist kein Datum.
`208`	Der Wert ist keine E-Mail-Adresse.
`209`	Der Wert ist keine URL.
`210`	Der Wert ist kein gültiges JSON.
`999`	Es liegt ein anderer Fehler bei diesem Wert vor.

Eine ID aus einem anderen Konto erzeugt dieselbe Meldung wie eine ID, die überhaupt nicht existiert: Unknown list mit dem Code 203. Das ist beabsichtigt, damit keine Rückschlüsse auf die Inhalte anderer Konten möglich sind.

Wie viele Anfragen dürfen Sie stellen?

Wie sieht eine Fehlermeldung aus?

Statuscodes

Fehlercodes

Verwandte Artikel