Troubleshooting

❌ Invalid API Key

Error: Invalid API key

Solution: Double-check your API key in the dashboard. Ensure there are no extra spaces or characters.

❌ Incorrect Form Action

Error: Form submits but nothing happens

Solution: Verify your form action URL:

❌ CORS Errors

Error: Access to fetch blocked by CORS policy

Solution: Static Forms supports CORS by default. If you see this error, check your browser console for the exact error message. Ensure you're using the correct endpoint URL.

❌ 403 — Domain Not Allowed

Error: Submissions from this domain are not allowed.

Solution: If you have domain restrictions enabled in your account settings, your form's origin domain must be on the allowed list. Add the domain (e.g. example.com) in your dashboard under Domain Restrictions, or disable the restriction entirely. See the domain restriction docs for details.

❌ 403 — CAPTCHA Verification Failed

Error: CAPTCHA verification failed. Please try again.

Solution: The CAPTCHA token was missing, expired, or invalid. Ensure the CAPTCHA widget completes before the form is submitted and that the token field name matches what Static Forms expects (g-recaptcha-response for reCAPTCHA v2, recaptchaToken for reCAPTCHA v3, cf-turnstile-response for Turnstile, or altchaToken for ALTCHA).

📧 Email in Spam Folder

Emails may be filtered by spam filters. Check your spam/junk folder and mark the email as "Not Spam". Add noreply@staticforms.dev to your contacts to prevent future filtering.

🔒 Email Not Verified

Error: Email not verified

Solution: Verify your email address in your account settings. Check your inbox for the verification email.

📊 Submission Limit Exceeded

Error: Monthly submission limit (<limit>) exceeded for your account tier (<tier>). The API uses this wording on every plan, including Free, whose limit resets every 30 days. On Pro and Agency, if the message adds that overage billing is paused due to an unpaid invoice, update your payment method in billing to resume overage.

Solution: Check your current usage in the dashboard. Free: 250 submissions every 30 days. Starter: 3,000 submissions per month, Pro: 25,000, Agency: 30,000. On Free and Starter, submissions past the quota are held in your inbox, not rejected, and are released when the quota resets or you move to a plan that covers them. Up to 100 are held per period; after that new submissions get a 429. Pro and Agency can opt into overage at $1.00 per 1,000 extra submissions. Free's limit resets every 30 days, paid plans reset monthly: at each renewal on monthly billing, and every 30 days on yearly billing, and a trial's allowance does not reset.

🚫 Form Submission Blocked by Spam Detection

No error shown, but email not received

Solution: If honeypot fields are filled or CAPTCHA fails, submissions are silently rejected. Check your form implementation:

• Ensure honeypot fields are hidden from users
• Verify CAPTCHA is properly configured
• Check that form fields are not auto-filled by bots

📭 Account Email Address Has Bounced

API returns 200 (success), but no email is received

Cause: If a previous email to your account address was undeliverable (hard bounce), further delivery is automatically blocked to protect sender reputation. The form submission is still recorded in your dashboard, but no notification email is sent.

Solution: Update the email address in your account settings to a working address, then contact support to have the bounce record cleared.

❌ Submission Too Large

Error: HTTP 413 (Request Entity Too Large), sent by the hosting platform before Static Forms processes the submission. A plain HTML form shows a hosting error page on api.staticforms.dev and your redirectTo page is not used. A fetch or AJAX call from your site sees a network error, because this response has no CORS headers. Only server-side requests sending Accept: application/json get a JSON body.

Solution: The whole submission, counting every file plus the other fields, must stay under 4.5MB. Keep all files together under 4MB and check the total in the browser before submitting, which is the only way to show a friendly message (see client-side validation). Compress images or split large files before uploading.

❌ Invalid File Type

Error: File type not supported

Solution: Supported formats: PDF, DOC, DOCX, JPG, PNG, GIF, WEBP, TXT, RTF. Ensure your file matches one of these types.

❌ Missing enctype Attribute

Error: Files not being uploaded

Solution: Add enctype="multipart/form-data" to your form:

🔒 Paid Plan Required

Error: File uploads require the Starter plan or above

Solution: File uploads are available from the Starter plan up ($6/month, or $4/month billed annually), with 1 GB of storage on Starter, 5 GB on Pro, and 10 GB on Agency. Upgrade your plan to enable file uploads.

🚫 429 Too Many Requests

Error: Rate limit exceeded

For Form Submissions: You've sent too many submissions in a short time (per minute, or per hour for this API key). Wait and retry; the error message says which limit applies. If you've used your plan's quota instead, see Submission Limit Exceeded above.

For ALTCHA Challenge: You've made more than 10 requests per minute. Wait a minute before retrying.

📈 Check Your Usage

Visit your dashboard to see your current usage and when limits reset. Free resets every 30 days, paid plans reset monthly: at each renewal on monthly billing, and every 30 days on yearly billing, and a trial's allowance does not reset. Each step up the ladder — Starter, Pro, Agency — raises the limit.

❌ CAPTCHA Provider Not Working

Check:

• Site key and secret key are correctly configured in settings
• The provider script is loaded before form submission
• Field name matches your provider: g-recaptcha-response, recaptchaToken, cf-turnstile-response, or altchaToken
• Your domain is registered with the provider if required
• Using Turnstile? See Turnstile test keys, localhost and token errors

❌ ALTCHA Challenge Not Loading

Check:

• ALTCHA script is loaded: altcha.js
• Challenge URL is correct: https://www.staticforms.dev/api/altcha/challenge?apiKey=YOUR_API_KEY
• ALTCHA is enabled in your account settings
• Check browser console for JavaScript errors

❌ Invalid API Key

Error: Invalid API key

Solution: Copy your API key directly from the dashboard. Ensure there are no extra spaces or line breaks. API keys are case-sensitive.

❌ API Key Missing

Error: API key is required

Solution: Ensure your form includes a hidden input field with your API key:

🔄 Regenerate API Key

If you suspect your API key is compromised, you can regenerate it in your account settings. Note: You'll need to update all forms using the old key.