API & developer surface
This page is for developers integrating against Fola’s REST API
(api.folaform.com), the @folaform/forms-sdk npm package, or
inbound webhooks. If you’re not a developer, skip this page — the
rest of the troubleshooting library covers everything you’ll need.
”401 Unauthorized on every API request”
Section titled “”401 Unauthorized on every API request””What it means: your bearer token expired or your API key was revoked.
What to do:
- JWT-based auth (workspace tokens): log into the workspace
to refresh, then re-grab the token from
localStorage(key:fola.workspace.tokens.v1). - API key auth: generate a new key at Settings → API keys. Old key is revoked immediately.
”429 Too Many Requests”
Section titled “”429 Too Many Requests””What it means: you hit the rate limit. Defaults: 60 requests per minute per API key, 600 per hour per org.
What to do:
- Honor the
Retry-Afterheader in the 429 response — wait that many seconds before retrying. - For sustained higher throughput, distribute across multiple API keys (each gets its own per-key limit).
- Enterprise tier raises both limits; talk to support@folaform.com.
”Webhook never fires”
Section titled “”Webhook never fires””What it means: your webhook endpoint is either disabled, or returned non-2xx on the first three delivery attempts (after which Fola stops retrying).
What to do:
- Open Settings → Webhooks and check the Last delivery status column.
- If “Disabled”, re-enable.
- If “Permanent failure”, look at your endpoint logs — it probably 500’d. Fix the bug, then click Replay on the failed deliveries.
”Webhook signature verification fails”
Section titled “”Webhook signature verification fails””What it means: you’re verifying against the wrong shared secret, or your endpoint’s body parser is mutating the request body before you sign-check.
What to do:
- Verify against the raw request body (before JSON parse).
- The HMAC payload is
<timestamp>.<raw-body>, SHA-256-signed with your webhook secret. - The signature header is
X-Fola-Signature: t=<timestamp>,v1=<hex-hash>. - If you rotated the secret recently, your code may still be using the old one. Re-pull it from Settings → Webhooks → [your endpoint] → Show secret.
”OpenAPI spec doesn’t match the actual API”
Section titled “”OpenAPI spec doesn’t match the actual API””What it means: the spec at /api/v1/openapi.json is generated
from backend source — usually in sync, but minor drift happens.
What to do: trust the actual API response over the spec. If you see drift on a meaningful field, email developer@folaform.com with the endpoint + the discrepancy; we re-export the spec on a fast turnaround.
”SDK type errors after npm install”
Section titled “”SDK type errors after npm install””What it means: the SDK’s typed schemas are generated from the backend form definitions. If the SDK version doesn’t match the backend version, types can drift.
What to do:
- Pin the SDK to the latest published version:
npm install @folaform/forms-sdk@latest. - If your code references a form ID that’s been renamed or removed, type-check will catch it at compile time — update your usage to the new ID.
”API returns 402 Payment Required”
Section titled “”API returns 402 Payment Required””What it means: the action you tried to take (e.g. running AI Autofill via API) exceeds your monthly cap and overage isn’t configured.
What to do: add a card to your firm’s account at Settings → Billing → Payment method, OR upgrade to a tier that includes the headroom you need.
”API returns 409 firm_service_agreement_required”
Section titled “”API returns 409 firm_service_agreement_required””What it means: you tried to start a subscription via API on an org that hasn’t signed the service agreement.
What to do: the signing flow is workspace-only (signature is a drawn canvas, not API-exposable). Have an admin sign at Settings → Service agreement, then retry the subscribe API call.
”Unknown field on form fill via API”
Section titled “”Unknown field on form fill via API””What it means: your API payload uses a field name that doesn’t match the form’s definition.
What to do:
- Fetch the form definition first:
GET /api/v1/forms/[form-id]. - Use the exact field keys from
inputs[*].keyin the response. - Don’t invent or camelCase keys — the schema is authoritative.
When to email vs when to handle in-code
Section titled “When to email vs when to handle in-code”- Auth / rate limit / 4xx errors — handle in-code (refresh tokens, honor Retry-After, fix payload)
- Webhook signature problems — handle in-code
- OpenAPI drift — email developer@folaform.com
- Sustained 5xx on a specific endpoint — email developer@folaform.com with the request ID
Was this page helpful?
Thanks — noted.