Fehler

Fehler kommen immer im Format RFC 9457 als application/problem+json:

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json

{
  "type": "https://docs.grem.capital/api/errors/business_rule",
  "title": "business_rule",
  "status": 422,
  "detail": "Describe the property: pick a listing or fill in at least a description, city or area",
  "code": "not_enough_input",
  "requestId": "req_..."
}

Ein Validierungsfehler mit Feldern:

{
  "title": "validation",
  "status": 400,
  "detail": "\"avatarId\" is required",
  "errors": [{ "field": "avatarId", "message": "\"avatarId\" is required" }],
  "requestId": "req_..."
}

Fehlercodes

Die URL in type führt zum passenden Eintrag dieser Liste.

invalid_key

401. Schlüssel fehlt, ist falsch, widerrufen oder abgelaufen. Prüfen Sie den Header Authorization und den Schlüsselstatus im Kabinett.

forbidden_scope

403. Der Schlüssel ist gültig, hat aber nicht den nötigen Bereich. Erteilen Sie den Bereich oder erstellen Sie einen neuen Schlüssel (Authentifizierung).

forbidden

403. Die Aktion ist für dieses Konto oder diese Ressource nicht erlaubt: etwa gehört das Objekt einem anderen Konto oder die Rolle in der Agentur reicht nicht. Der Grund steht in detail.

insufficient_funds

402. Nicht genug Guthaben im Wallet, das Planskontingent ist aufgebraucht, eine Schuld ist offen oder das Fair-Use-Limit ist erreicht. code nennt den Grund: INSUFFICIENT_FUNDS, QUOTA_EXCEEDED, DEBT_OUTSTANDING, FAIR_USE_LIMIT_REACHED und so weiter. Laden Sie auf, begleichen Sie die Schuld oder wechseln Sie den Tarif.

validation

400. Die Anfrage hat die Prüfung nicht bestanden. Was genau falsch ist, steht in detail und errors. Korrigieren Sie die Anfrage; eine unveränderte Wiederholung bringt nichts.

business_rule

422. Die Anfrage ist korrekt aufgebaut, lässt sich aber nicht ausführen: Daten fehlen, das Objekt ist im falschen Zustand, der Immobilientyp wird nicht unterstützt usw. Grund in detail, Maschinencode in code.

payload_too_large

413. Body oder Datei über dem Limit. Die Größenlimits stehen beim jeweiligen Werkzeug. Ein Body, der kein gültiges JSON ist, ergibt 400 validation.

range_not_satisfiable

416. Der Range eines Datei-Downloads liegt außerhalb der Datei. Content-Range: bytes */size nennt die Dateigröße.

rate_limited

429. Ratenlimit überschritten. Warten Sie so viele Sekunden wie in Retry-After und wiederholen Sie (Limits und Abrechnung). code nennt das Limit: minute_limit (Sekunden) oder daily_limit (zurückgesetzt um 00:00 UTC).

not_found

404. Unbekannter Pfad oder eine Ressource, die nicht existiert oder nicht Ihnen gehört. Eine fremde Ressource erhält bewusst dieselbe Antwort wie eine fehlende.

idempotency_conflict

409. Eine Anfrage mit diesem Idempotency-Key läuft noch. Warten Sie das Ende ab und wiederholen Sie mit demselben Schlüssel (Idempotenz). Nach einer Zeitüberschreitung (502 provider_error) bleibt der Schlüssel 15 Minuten gesperrt: Prüfen Sie das Ergebnis, bevor Sie wiederholen - eine Wiederholung nach der Sperre führt die bezahlte Arbeit erneut aus. Die Express-Bewertung gibt den Schlüssel nach einer Zeitüberschreitung frei: Wiederholen Sie sie mit demselben Schlüssel. Dasselbe 409 kommt, wenn die Zahlung für einen Aufruf mit diesem Schlüssel noch reserviert wird (code RESERVE_IN_PROGRESS, RESERVE_BUSY) - später wiederholen; RESERVE_REF_TAKEN - der Schlüssel ist verbraucht, senden Sie einen neuen.

conflict

409. Die Ressource ist in einem Zustand, der diese Aktion nicht erlaubt (zum Beispiel ein Objekt von einer Agentur in eine andere verschieben, ein Objekt mit laufendem Provisionsvertrag löschen). Der Grund steht in detail. Wiederholen Sie die Anfrage nicht unverändert.

service_unavailable

503. Das Werkzeug ist vorübergehend nicht verfügbar. Nichts wurde berechnet. Wiederholen Sie nach der Pause aus Retry-After; den aktuellen Zustand zeigt GET /tools/status.

provider_error

502. Der ausführende Dienst ist ausgefallen. Vorübergehend: mit wachsender Pause wiederholen. Sagt detail, dass das Werkzeug nicht rechtzeitig geantwortet hat, kann die Arbeit noch fertig und berechnet werden: Prüfen Sie GET /works, bevor Sie sie erneut starten; die Express-Bewertung wiederholen Sie mit demselben Idempotency-Key. Ergebnisse von Fotoverbesserung, Website und Entwurf werden in GET /works nicht geführt: Warten Sie bei ihnen die 15-minütige Sperre ab und prüfen Sie das Ergebnis im Kabinett oder unter Ihren Objekten.

internal_error

500. Interner Fehler. Mit Pause wiederholen; tritt er weiter auf, wenden Sie sich mit der requestId an den Support.

Die Liste kann wachsen. Behandeln Sie einen unbekannten Code als allgemeinen Fehler seiner HTTP-Klasse (4xx - Anfrageproblem, 5xx - Dienstausfall).

Was wiederholen

Senden Sie bei Wiederholungen erzeugender Anfragen immer denselben Idempotency-Key - dann wird die Arbeit weder doppelt ausgeführt noch doppelt berechnet.

Ausnahmen

• Swipe-Match-Ereignisse (POST /match/leads/{id}/events), die der aktuelle Lead-Zustand nicht erlaubt, antworten mit 409, title: business_rule und dem Grund in code (client_event_rejected, invalid_transition, not_available).
• Aktionen mit dem Lead-Pool der Agentur (POST /leads/{id}/claim, POST /leads/{id}/return-to-pool) mit persönlichem Schlüssel oder unzureichender Rolle antworten mit 403 und title: forbidden.

Was nicht berechnet wird

Eine abgelehnte Anfrage (jede Antwort 4xx oder 5xx) verbraucht keinen API-Aufruf. Der Werkzeugpreis wird nur für angenommene Arbeit berechnet. Ausnahme ist provider_error nach einer Zeitüberschreitung: Die Arbeit kann trotzdem fertig werden und berechnet werden - prüfen Sie GET /works, bevor Sie sie neu starten (Fotoverbesserung, Website und Entwurf: im Kabinett oder unter Ihren Objekten).

Verwandte Artikel

• Limits und Abrechnung
• Idempotenz
• Authentifizierung