Zum Hauptinhalt springen

Public API – Fehlercodes & Rate-Limits

HTTP-Statuscodes, typische Fehler und Rate-Limit (120/min).

Verfasst von Support Team

So erkennst du Fehler und bleibst innerhalb der Limits.

Basis-URL:https://de.rip-app.business/api/public/v1 – Details: Public API – Einstieg & Authentifizierung.

Antwortformat

Erfolg:

{ "success": true, "data": { } }

Listen von Trauerfällen, Terminen und Dokumenten zusätzlich mit count:

{ "success": true, "count": 3, "data": [ ] }

Die Lookup-Listen (/burial-types, /branches, /users, /document-tags) liefern nur data.

Fehler:

{ "success": false, "error": "Kurze Beschreibung" }

Fehlertexte sind zur Anzeige gedacht, nicht zum Auswerten. Verlasse dich in deiner Logik auf den HTTP-Statuscode, nicht auf den Text.

HTTP-Statuscodes

Code

Bedeutung

Was tun?

200 / 201

Alles ok

–

400

Ungültige Anfrage / fehlende Felder

Body und Pflichtfelder prüfen

401

Token fehlt oder ungültig

Key prüfen / neu erzeugen

403

Public API nicht freigeschaltet oder Feature-Gate

Im Shop als zusätzlichen Service buchen

404

Endpoint, Version oder Ressource nicht gefunden

Pfad, /v1 und UUID prüfen

405

Methode nicht erlaubt

HTTP-Methode prüfen

409

Konflikt (z. B. schon abgeschlossen, Tag schon vergeben)

Status des Falls prüfen

429

Rate-Limit erreicht

Retry-After abwarten

500

Serverfehler

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

Versions-Header

Jede erfolgreiche Antwort enthält die bediente Version:

X-API-Version: v1

Pfade ohne /v1 oder mit unbekannter Version antworten mit 404 und supported_versions.

Rate-Limit

  • 120 Anfragen pro Minute pro API-Key

  • Bei fehlgeschlagenen Auth-Versuchen zusätzlich ein IP-Limit (20 Versuche pro 15 Minuten)

  • Bei Überschreitung: Status 429, Header Retry-After (Sekunden) und Feld retry_after

Beispiel:

{
  "success": false,
  "error": "Zu viele Anfragen. Bitte später erneut versuchen.",
  "retry_after": 42
}

curl -sD - -o /dev/null \
  -H "Authorization: Bearer rip_pub_DEIN_TOKEN" \
  "https://de.rip-app.business/api/public/v1/me" | grep -i retry-after

const res = await fetch(`${base}/me`, {
  headers: { Authorization: `Bearer ${token}` },
});
if (res.status === 429) {
  const retryAfter = Number(res.headers.get("Retry-After") || 60);
  await new Promise((r) => setTimeout(r, retryAfter * 1000));
}

Typische Fehler

Kein Header

{ "success": false, "error": "Authorization required" }

Falscher oder widerrufener Key

{ "success": false, "error": "Invalid or expired token" }

Feature nicht aktiv

{ "success": false, "error": "Public API ist für diese Organisation nicht freigeschaltet" }

Ungültige UUID

{ "success": false, "error": "Ungueltige UUID" }

Endpoint unbekannt

{ "success": false, "error": "Endpoint not found" }

Falsche Methode

{ "success": false, "error": "Method not allowed" }

Sonderfall Datei-Download

GET /documents/{doc_uuid}/download liefert im Erfolgsfall die Datei selbst, kein JSON. Im Fehlerfall kommt der Statuscode mit einer Klartext-Meldung statt eines JSON-Objekts. Prüfe hier also den Statuscode, bevor du den Body verarbeitest.

Sicherheit

  • API-Keys nie in öffentliche Repos oder Frontend-Code legen

  • Pro User nur ein aktiver Key – bei Verdacht neuen erzeugen (der alte wird ungültig)

  • Keys widerrufen unter Einstellungen → Anwendung

  • Key und Basis-URL immer zur gleichen Instanz nutzen

Hat dies deine Frage beantwortet?