Fehlerbehebung

Fang mit der Antwort an. Jede Antwort von Ikiform hat einen Header X-Request-Id und bei Fehlern einen stabilen error.code. Dieser curl-Befehl zeigt beides, vom selben Origin, von dem deine Site senden würde:

curl -i https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Origin: https://example.com" \
  -d '{"email":"ada@example.com"}'

Siehst du 5xx-Fehler oder Timeouts von Ikiform selbst? Prüf zuerst status.ikiform.com auf aktuelle Störungen.

Der Browser meldet, dass CORS den Request blockiert hat

Der Einsendungs-Endpunkt erlaubt jeden Origin, ein echter CORS-Fehler bedeutet daher meist, dass der Request Ikiform nie erreicht hat oder an die falsche URL ging.

• Prüf, ob die URL https://ikiform.com/f/<formId> mit der vollständigen frm_-ID ist, zum Beispiel frm_xxxxxxxxxxxxxxxx, ohne angehängten Pfad.
• Du rufst /api/v1 aus einem Browser auf. Die REST-API lehnt Browser absichtlich ab; ruf sie von deinem Server aus auf.
• Ein Adblocker, eine Datenschutz-Erweiterung oder ein Firmen-Proxy hat den Request blockiert. Probier ein privates Fenster ohne Erweiterungen.
• Die eigene Content-Security-Policy deiner Site blockiert ihn. Füge https://ikiform.com zu connect-src hinzu, und für einfache HTML-Posts zu form-action.

Prüf den Preflight direkt; er sollte mit 204 antworten und deinen Origin zurückgeben:

curl -i -X OPTIONS https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx \
  -H "Origin: https://example.com" \
  -H "Access-Control-Request-Method: POST" \
  -H "Access-Control-Request-Headers: content-type"

Einsendungen landen mit origin_mismatch im Spam

Das Formular hat erlaubte Domains und der Post kam von woanders. Das Dashboard zeigt origin_mismatch unter den Spam-Gründen.

• Füge jede Domain hinzu, von der das Formular ausgeliefert wird, einschließlich www, Staging- und Preview-Domains. Subdomains einer eingetragenen Domain passen bereits.
• Füge localhost hinzu, während du lokal entwickelst.
• Posts von deinem eigenen Server tragen kein Origin. Sende einen Secret Key, der die Prüfung überspringt.
• Wenn Reject statt Mark as spam gewählt ist, erhalten dieselben Posts 403 origin_not_allowed.

403 challenge_required

Die Spamprüfung des Formulars steht auf Ikiform und der Post hatte kein Turnstile-Token.

1. Browser-Code: Ruf challenge(formId) aus dem SDK direkt vor jedem Absenden auf und übergib das Token als turnstileToken an submit.
2. Server-Code: Sende Authorization: Bearer ik_sk_... mit einem Secret Key; Secret Keys überspringen die Prüfung.
3. Einfache HTML-Posts sehen diesen Code nie; sie erhalten stattdessen die Prüfseite. Wenn du ihn bei einem Formular-Post siehst, sendet etwas Accept: application/json.
4. Testest du mit curl? Schalte die Prüfung für ein Testformular ab, oder nutze einen Secret Key.

403 captcha_failed bedeutet, dass ein Token gesendet, aber nicht verifiziert wurde. Tokens sind einmalig gültig und laufen nach 300 Sekunden ab, also hol dir für jeden Versuch ein neues.

429 rate_limited

• Lies Retry-After und warte so viele Sekunden.
• Testest du von Hand? Die Voreinstellung Standard erlaubt 5 Posts pro Minute von einer IP und 3 in 10 Sekunden. Stell ein Testformular auf Relaxed um.
• Sendest du für jeden Besucher von deinem Server? Alle Posts teilen sich die IP deines Servers. Sende aus dem Browser, oder wähle Relaxed oder Custom.
• Viele Menschen hinter einem Büro- oder Event-Netzwerk teilen sich ebenfalls eine IP. Relaxed erlaubt 20 pro Minute.

422 mit Unknown field

Das Formular hat definierte Felder und der Post hat einen Namen gesendet, der nicht in der Definition steht. error.fields nennt ihn, zum Beispiel { "website": ["Unknown field \"website\""] }.

• Füge das Feld zur Definition hinzu, oder entferne den Input.
• Benenne den Input so um, dass er mit _ beginnt, wenn er nur eine Markierung für dich ist; reservierte Namen werden verworfen, nicht validiert.
• Prüf, ob der Honeypot-Name zur Einstellung Honeypot field des Formulars passt.
• Feld-IDs sind snake_case in Kleinbuchstaben: firstName in deinem Markup ist nicht dasselbe wie first_name in der Definition.

429 quota_exceeded

Der Workspace hat diesen Monat das Doppelte seines monatlichen Limits erhalten und nimmt keine Einsendungen mehr an, bis der nächste Monat beginnt oder der Workspace upgradet. Siehe Monatliche Nutzung.

Einsendungen tauchen nicht auf

• Schau unter dem Spamfilter nach. Spam erhält eine normale Erfolgsantwort, daher merkt der Besucher nichts.
• Prüf, ob das Formular nicht pausiert ist und ob die ID in deinem action mit dem Dashboard übereinstimmt.
• Ein Browser-Post, der die Fehlerseite von Ikiform zeigt, wurde abgelehnt; die Seite nennt den Grund.

Webhooks schlagen fehl

• no_matching_signature: Verifiziere gegen den rohen Body, vor jedem JSON-Parsing, und prüf, ob du das richtige whsec_-Secret kopiert hast. Füge eine Zustellung in den Verifizierer ein.
• timestamp_too_old: Die Uhr deines Servers geht falsch, oder du spielst eine alte Zustellung erneut ein.
• Timeouts: Antworte innerhalb von 15 Sekunden und erledige langsame Arbeit danach.
• Weiterleitungen werden nicht gefolgt. Nutze die endgültige URL, einschließlich des abschließenden Schrägstrichs, den dein Framework erwartet.
• Der Endpunkt wurde nach 5 Tagen mit Fehlern oder einem 410 deaktiviert. Behebe das Problem und schalte ihn dann auf der Seite des Endpunkts wieder ein.