Fehlerbehebung bei Requests

Einen Fehler lesen

Jede Ablehnung trägt zwei Dinge: einen code für die Art des Fehlers, und einen details.reason für die konkrete Ursache. Verzweige nach dem Code; lies den Grund, um zu wissen, was zu beheben ist. Wo es hilft, nennt details auch das betroffene field, die Schlüssel, die akzeptiert worden wären, oder die Optionsschlüssel, die eine Auswahlfrage annimmt.

Die Request-Methoden verwenden vier Codes: VALIDATION_ERROR (der Aufruf war falsch), CONFLICT (der Request ist im falschen Zustand, oder ein Idempotenz-Schlüssel wurde wiederverwendet), NOT_FOUND, und UPGRADE_REQUIRED (eine Plan-Schranke oder das monatliche Kontingent). Ruft man zu schnell auf, kommt stattdessen RATE_LIMITED zurück, mit retryAfterMs — siehe die Ratenbegrenzung.

{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "No field with key \"company\".",
    "details": { "reason": "UNKNOWN_FIELD_KEY", "field": "prefill.company", "validKeys": ["company_name", "company_size"] }
  }
}

Gründe, die dir begegnen könnten

Den Aufruf richtig hinbekommen

Auf einen bestehenden Request einwirken

Die Einladung ist nie angekommen

Öffne den Request auf der Requests-Seite und lies die Timeline. Die erste Einladungszeile sagt dir, welcher Fall vorliegt.

Einladungen und Erinnerungen teilen sich ein Budget von zehn E-Mails pro Tag pro Formular und Empfängeradresse, und ein Request schickt seiner empfangenden Person höchstens neun E-Mails in seinem gesamten Leben — eine Einladung und bis zu acht Erinnerungen.

Der Callback ist nie angekommen

Der Abschnitt Callback in der Request-Detailansicht zeigt die URL und das Ergebnis. Callback nach N Versuchen fehlgeschlagen bedeutet, formbase hat es versucht und aufgegeben — acht Versuche über etwa vier Stunden.

1. Prüfe die URL. Sie wird in der Detailansicht angezeigt. Die Resume-URL eines Workflow-Tools gehört zu einem Lauf, und ein gelöschter oder neu erstellter Lauf antwortet darauf nicht mehr.

2. Prüfe, was dein Endpunkt zurückgegeben hat. Alles außerhalb von 2xx ist ein Fehlschlag. Ein 4xx außer 408 oder 429 stoppt die Wiederholungen sofort — formbase liest das als “dein Endpunkt hat das abgelehnt”, und dieselben Bytes erneut zu senden kann daran nichts ändern.

3. Behebe den Empfänger, dann drücke Erneut senden (Replay). Dasselbe Payload geht mit derselben Ereignis-ID erneut hinaus, sodass ein deduplizierender Empfänger sicher ist.

Andere Dinge, auf die Leute stoßen

• Die empfangende Person sagt, der Link zeigt einen Hinweis statt des Formulars. Der Request ist endgültig — abgeschlossen, abgelaufen oder storniert. Das ist die Ergebnisseite. Erstelle einen neuen Request, wenn sie es erneut versuchen soll.

• Eine Automation hat nach einer Bearbeitung aufgehört zu passen — eine Antwort fehlte plötzlich im Callback, oder requests.create fing an, einen Schlüssel mit UNKNOWN_FIELD_KEY abzulehnen. Ein veröffentlichter Feldschlüssel ist verschwunden: Jemand hat ihn neu getippt, oder die Frage gelöscht und an ihrer Stelle eine neue hinzugefügt. Umbenennen des Titels ist sicher; beides davon nicht. Tippe den alten Schlüssel auf das Feld (Schlüssel-Symbol in der Symbolleiste → Schlüssel) und veröffentliche erneut. Die Veröffentlichung warnt, bevor das passiert — siehe Wenn ein veröffentlichter Schlüssel gleich verschwindet.

• Prefill für einen Datei-Upload oder eine Signatur wird abgelehnt. Diese können nicht von einer aufrufenden Seite geliefert werden — fields.list markiert sie mit prefillable: false.

• Zwei Requests sind für einen Workflow-Lauf entstanden. Der Lauf wurde ohne idempotencyKey wiederholt. Übergib die Ausführungs-ID als Schlüssel.