Die Public API meldet Fehler über den HTTP-Statuscode und ein kurzes JSON-Objekt. Werte in deiner Integration immer den Statuscode aus. Die Texte sind für Menschen gedacht und können sich ändern.
Fehlerformat
{
"success": false,
"error": "Sterbefall nicht gefunden"
}
Bei 429 kommt zusätzlich retry_after (Sekunden) dazu, bei einer unbekannten API-Version supported_versions.
Zwei Ausnahmen:
Datei-Download.
GET /documents/{uuid}/downloadantwortet im Fehlerfall mit reinem Text (Content-Type: text/plain), zum BeispielDokument nicht gefunden.Unerwartete Serverfehler. Bei
500kann der Body leer sein. Lies den Body nur als JSON, wenn derContent-Typeapplication/jsonist.
Statuscodes
Code | Bedeutung | Was du tun solltest |
| Erfolg | – |
| Angelegt ( | – |
| Anfrage ungültig: falsches JSON, Pflichtfeld fehlt, falsches Format, unbekannte ID | Anfrage korrigieren, nicht unverändert wiederholen |
| API-Key fehlt oder ist ungültig | Key prüfen oder neu erzeugen |
| Modul nicht gebucht, Benutzer ohne Unternehmen oder Funktion nicht freigeschaltet | Buchung im Shop und Benutzer prüfen |
| Endpunkt, Version oder Datensatz nicht gefunden | Pfad, |
| Methode für diesen Pfad nicht erlaubt | HTTP-Methode prüfen |
| Konflikt mit dem Zustand des Falls, zum Beispiel schon abgeschlossen | Fall abrufen und Zustand prüfen |
| Rate-Limit erreicht |
|
| Fehler auf unserer Seite | Später wiederholen; bleibt es dabei, melde dich beim Support |
| Wartungsarbeiten | Später wiederholen |
Manche Pfade antworten bei einer nicht unterstützten Methode mit 404 statt 405. Behandle beide als „gibt es so nicht“.
Häufige Fehlermeldungen
Die Texte stammen von der deutschen Region. Auf nl sind sie englisch.
Code |
| Ursache |
|
| Body fehlt oder ist kein gültiges JSON |
|
| UUID im Pfad hat nicht das Format |
|
|
|
|
| Datum nicht im Format |
|
|
|
|
|
|
|
| Prozessschritt gesetzt, aber der Fall hat keine Bestattungsart |
|
|
|
|
| Abschließen ohne Koordinaten |
|
|
|
|
| Upload zu groß |
|
| Dateityp nicht erlaubt |
|
| Startcode existiert nicht |
|
| Header fehlt oder Key hat nicht das Format |
|
| Key unbekannt, widerrufen oder ersetzt, oder Benutzer entfernt bzw. Konto gelöscht |
|
| Modul nicht gebucht |
|
| Benutzer des Keys gehört keinem Unternehmen mehr an |
|
| Pfad gibt es nicht |
|
| UUID unbekannt oder aus einem anderen Unternehmen |
|
| UUID unbekannt |
|
| Methode passt nicht zum Pfad |
|
| Fall wurde schon abgeschlossen |
|
| Fall hat schon einen RIP Tag |
|
| Allgemeines Rate-Limit erreicht |
Weitere Meldungen findest du bei den einzelnen Endpunkten.
Rate-Limits
Bereich | Limit | Gilt für | Verhalten |
Alle Anfragen | 120 Anfragen je 60 Sekunden | pro API-Key | Das Zeitfenster beginnt mit der ersten Anfrage. Ist das Limit erreicht, antwortet die API bis zum Ende des Fensters mit |
Fehlgeschlagene Anmeldung | 20 Fehlversuche je 15 Minuten | pro IP-Adresse | Danach kommt |
RIP Tag verbinden | 10 Versuche je 15 Minuten | pro IP-Adresse | Gemeinsames Limit mit der Startcode-Eingabe in Web und App von derselben IP-Adresse. Eine erfolgreiche Verbindung setzt den Zähler zurück. |
Mitgezählt werden alle Anfragen mit gültigem Key, auch solche, die mit 400 oder 404 enden. Header mit dem verbleibenden Kontingent gibt es nicht.
Antwort bei 429
HTTP/1.1 429 Too Many Requests
Retry-After: 37
Content-Type: application/json; charset=utf-8
{"success":false,"error":"Zu viele Anfragen. Bitte später erneut versuchen.","retry_after":37}
Beim Limit für RIP Tags steht die Wartezeit nur im Body (retry_after), nicht im Header.
Auf 429 und 503 reagieren
Warte die angegebene Zeit ab und versuche es dann erneut. Ein Beispiel für Node.js 18+:
const BASE_URL = "https://de.rip-app.business/api/public/v1";
async function ripRequest(path, options = {}, attempt = 1) {
const res = await fetch(`${BASE_URL}${path}`, {
...options,
headers: {
Authorization: `Bearer ${process.env.RIP_API_KEY}`,
...options.headers,
},
});
const retryable = res.status === 429 || res.status === 503;
if (retryable && attempt <= 3) {
const body = await res.clone().json().catch(() => ({}));
const seconds = Number(res.headers.get("Retry-After") ?? body.retry_after ?? 60);
await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
return ripRequest(path, options, attempt + 1);
}
return res;
}
So bleibst du sicher unter dem Limit:
Speichere Referenzdaten (Bestattungsarten, Standorte, Mitarbeiter, Tags) zwischen, statt sie vor jedem Request zu laden.
Frage
GET /casesnicht im Sekundentakt ab. Für Ereignisse im Prozess sind Webhooks gedacht.Verteile große Importe über die Zeit, zum Beispiel höchstens eine Anfrage pro Sekunde.
Wartungsarbeiten
Während Wartungsarbeiten antwortet die API mit 503:
{
"success": false,
"error": "maintenance",
"message": "Wir führen gerade Wartungsarbeiten durch. Bitte versuchen Sie es später erneut."
}
Der Text in message kann je nach Wartung abweichen.
Wenn ein Retry-After-Header mitkommt, richte dich danach. Sonst versuche es nach einigen Minuten erneut.