Zum Hauptinhalt springen

Public API – Fehler und Rate-Limits

Statuscodes, Fehlerformat, typische Fehlermeldungen und die Limits der Public API – und wie deine Integration darauf reagiert.

Verfasst von Support Team

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}/download antwortet im Fehlerfall mit reinem Text (Content-Type: text/plain), zum Beispiel Dokument nicht gefunden.

  • Unerwartete Serverfehler. Bei 500 kann der Body leer sein. Lies den Body nur als JSON, wenn der Content-Type application/json ist.

Statuscodes

Code

Bedeutung

Was du tun solltest

200

Erfolg

–

201

Angelegt (POST /cases, POST /cases/{uuid}/dates)

–

400

Anfrage ungültig: falsches JSON, Pflichtfeld fehlt, falsches Format, unbekannte ID

Anfrage korrigieren, nicht unverändert wiederholen

401

API-Key fehlt oder ist ungültig

Key prüfen oder neu erzeugen

403

Modul nicht gebucht, Benutzer ohne Unternehmen oder Funktion nicht freigeschaltet

Buchung im Shop und Benutzer prüfen

404

Endpunkt, Version oder Datensatz nicht gefunden

Pfad, /v1 und UUID prüfen

405

Methode für diesen Pfad nicht erlaubt

HTTP-Methode prüfen

409

Konflikt mit dem Zustand des Falls, zum Beispiel schon abgeschlossen

Fall abrufen und Zustand prüfen

429

Rate-Limit erreicht

Retry-After bzw. retry_after abwarten

500

Fehler auf unserer Seite

Später wiederholen; bleibt es dabei, melde dich beim Support

503

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

error

Ursache

400

Ungültige Anfrage

Body fehlt oder ist kein gültiges JSON

400

Ungültige UUID

UUID im Pfad hat nicht das Format 8-4-4-4-12

400

Vorname und Nachname sind Pflichtfelder

first_name oder last_name fehlt beim Anlegen

400

Ungültiges Sterbedatum (Format: YYYY-MM-DD)

Datum nicht im Format YYYY-MM-DD

400

Die ausgewählte Bestattungsart gehört nicht zur Organisation

burial_type_id unbekannt

400

Keine zu aktualisierenden Felder angegeben

PATCH ohne bekanntes Feld

400

Keine Bestattungsart zugewiesen

Prozessschritt gesetzt, aber der Fall hat keine Bestattungsart

400

Ungueltiger Schrittindex

current_step_index außerhalb der Schritte

400

Bestattungsort (Koordinaten) ist erforderlich

Abschließen ohne Koordinaten

400

Ungueltiger oder fehlender Termin

scheduled_at fehlt oder hat ein falsches Format

400

Datei darf maximal 25 MB groß sein

Upload zu groß

400

Dieser Dateityp ist nicht erlaubt (image/svg+xml)

Dateityp nicht erlaubt

400

Startcode ungültig

Startcode existiert nicht

401

Authorization required

Header fehlt oder Key hat nicht das Format rip_pub_…

401

Invalid or expired token

Key unbekannt, widerrufen oder ersetzt, oder Benutzer entfernt bzw. Konto gelöscht

403

Public API ist für diese Organisation nicht freigeschaltet

Modul nicht gebucht

403

Keine Organisation zugewiesen

Benutzer des Keys gehört keinem Unternehmen mehr an

404

Endpoint not found

Pfad gibt es nicht

404

Sterbefall nicht gefunden

UUID unbekannt oder aus einem anderen Unternehmen

404

Termin nicht gefunden / Dokument nicht gefunden

UUID unbekannt

405

Methode nicht erlaubt

Methode passt nicht zum Pfad

409

Dieser Trauerfall ist bereits abgeschlossen.

Fall wurde schon abgeschlossen

409

Diesem Sterbefall ist bereits ein RIP Tag zugewiesen

Fall hat schon einen RIP Tag

429

Zu viele Anfragen. Bitte später erneut versuchen.

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 429.

Fehlgeschlagene Anmeldung

20 Fehlversuche je 15 Minuten

pro IP-Adresse

Danach kommt 429 statt 401. Ein gültiger Key funktioniert weiter.

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 /cases nicht 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.

Hat dies deine Frage beantwortet?