Troubleshooting requests

Reading an error

Every rejection carries two things: a code for the kind of failure, and a details.reason for the specific cause. Branch on the code; read the reason to know what to fix. Where it helps, details also names the offending field, the keys that would have been accepted, or the option keys a choice question takes.

The request methods use four codes: VALIDATION_ERROR (the call was wrong), CONFLICT (the request is in the wrong state, or an idempotency key was reused), NOT_FOUND, and UPGRADE_REQUIRED (a plan gate or the monthly allowance). Calling too fast returns RATE_LIMITED instead, with retryAfterMs — see the rate limit.

{
  "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"] }
  }
}

Reasons you might see

Getting the call right

Acting on an existing request

The invitation never arrived

Open the request in the Requests page and read the timeline. The first invitation line tells you which case you are in.

Invitations and reminders share a budget of ten emails per day per form and recipient address, and a request never emails its recipient more than nine times in its life — one invitation and up to eight reminders.

The callback never landed

The request drawer’s Callback section shows the URL and the outcome. Callback failed after N attempts means formbase tried and gave up — eight attempts over about four hours.

1. Check the URL. It is shown in the drawer. A workflow tool’s resume URL belongs to one run, and a run that was deleted or re-created no longer answers on it.

2. Check what your endpoint returned. Anything outside 2xx is a failure. A 4xx other than 408 or 429 stops the retries immediately — formbase reads it as “your endpoint rejected this”, and re-sending identical bytes cannot change that.

3. Fix the receiver, then press Replay. The same payload goes out again with the same event id, so a receiver that deduplicates is safe.

Other things people hit

• The recipient says the link shows a notice, not the form. The request is terminal — completed, expired, or canceled. That is the outcome page. Create a new request if they need another go.

• An automation stopped matching after an edit — an answer went missing from the callback, or requests.create began refusing a key with UNKNOWN_FIELD_KEY. A published field key disappeared: someone retyped it, or deleted the question and added a new one in its place. Retitling is safe; both of those are not. Type the old key on the field (toolbar key icon → Keys) and publish again. Publish warns before this happens — see When a published key is about to disappear.

• Prefill for a file upload or a signature is refused. Those cannot be supplied by a caller — fields.list marks them prefillable: false.

• Two requests appeared for one workflow run. The run retried without an idempotencyKey. Pass the execution id as the key.