Fehlerbehandlung

Die API verwendet standardisierte Fehlercodes und -formate, um Probleme eindeutig zu kommunizieren.

Fehler-Format

Alle Fehler werden als JSON mit konsistentem Format zurückgegeben:

{
  "error": {
    "code": "error_code",
    "message": "Menschenlesbare Fehlerbeschreibung",
    "details": {
      "field": "Zusätzliche Informationen (optional)"
    }
  }
}

Feld	Typ	Beschreibung
`code`	String	Maschinenlesbarer Fehlercode
`message`	String	Menschenlesbare Beschreibung
`details`	Object	Zusätzliche Informationen (optional)

HTTP Status Codes

4xx Client-Fehler

Status	Code	Beschreibung	Aktion
400	`bad_request`	Ungültige Anfrage	Request-Parameter prüfen
401	`unauthorized`	Authentifizierung fehlgeschlagen	Token prüfen
403	`forbidden`	Zugriff verweigert	Scopes prüfen
404	`not_found`	Ressource nicht gefunden	ID/Slug prüfen
422	`unprocessable_entity`	Validierungsfehler	Request-Body prüfen
429	`rate_limit_exceeded`	Rate Limit erreicht	Warten und wiederholen

5xx Server-Fehler

Status	Code	Beschreibung	Aktion
500	`internal_error`	Interner Serverfehler	Support kontaktieren
503	`service_unavailable`	Service temporär nicht verfügbar	Später wiederholen

Authentifizierungs-Fehler (401)

missing_token

{
  "error": {
    "code": "missing_token",
    "message": "Missing Authorization header"
  }
}

Lösung: Füge den Authorization: Bearer rfk_... Header hinzu.

invalid_token_format

{
  "error": {
    "code": "invalid_token_format",
    "message": "Invalid token format. Token must start with 'rfk_'"
  }
}

Lösung: Stelle sicher, dass der Token mit rfk_ beginnt.

invalid_token

{
  "error": {
    "code": "invalid_token",
    "message": "The provided API token is invalid"
  }
}

Lösung: Überprüfe den Token oder erstelle einen neuen.

token_revoked

{
  "error": {
    "code": "token_revoked",
    "message": "This token has been revoked"
  }
}

Lösung: Erstelle einen neuen Token im Partner-Dashboard.

token_expired

{
  "error": {
    "code": "token_expired",
    "message": "This token has expired"
  }
}

Lösung: Erstelle einen neuen Token.

partner_inactive

{
  "error": {
    "code": "partner_inactive",
    "message": "Your API partner account is inactive"
  }
}

Lösung: Kontaktiere den Support.

Autorisierungs-Fehler (403)

insufficient_scope

{
  "error": {
    "code": "insufficient_scope",
    "message": "This endpoint requires the 'matching:use' scope"
  }
}

Lösung: Erstelle einen Token mit dem benötigten Scope.

Validierungs-Fehler (400/422)

Fehlende Parameter

{
  "error": {
    "code": "bad_request",
    "message": "organization_id is required"
  }
}

Ungültige Parameter

{
  "error": {
    "code": "unprocessable_entity",
    "message": "Validation failed",
    "details": {
      "legal_form": "is not a valid legal form"
    }
  }
}

Rate Limit-Fehler (429)

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please wait before retrying.",
    "retry_after": 30
  }
}

Lösung: Warte die angegebene Zeit (retry_after in Sekunden) und wiederhole die Anfrage.

Retry-Strategie

Welche Fehler sollten wiederholt werden?

Status	Retry?	Strategie
400	❌	Request korrigieren
401	❌	Token prüfen/erneuern
403	❌	Scope prüfen
404	❌	ID/Slug prüfen
422	❌	Request-Body korrigieren
429	✅	Nach `Retry-After` warten
500	✅	Exponential Backoff
503	✅	Exponential Backoff

Exponential Backoff Implementation

# Ruby
def with_retry(max_attempts: 3)
  attempts = 0

  begin
    attempts += 1
    yield
  rescue ApiError => e
    raise e unless e.retryable? && attempts < max_attempts

    sleep_time = (2 ** attempts) + rand
    sleep(sleep_time)
    retry
  end
end

with_retry do
  api_client.matching(params)
end

// JavaScript
async function withRetry(fn, maxAttempts = 3) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (!isRetryable(error) || attempt === maxAttempts) {
        throw error;
      }

      const sleepTime = Math.pow(2, attempt) * 1000 + Math.random() * 1000;
      await new Promise(resolve => setTimeout(resolve, sleepTime));
    }
  }
}

function isRetryable(error) {
  return [429, 500, 503].includes(error.status);
}

Fehler melden

Bei wiederholten 500-Fehlern oder unerwarteten Problemen:

Notiere den Zeitpunkt und die Request-Details
Erstelle ein Support-Ticket im Helpcenter
Füge den Fehlercode und die Message hinzu

Wir analysieren das Problem und melden uns schnellstmöglich zurück.

Suche

Menu