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.

📊 Monthly Limit Exceeded

Error: Monthly email limit exceeded

Solution: Check your current usage in the dashboard. Free tier: 500 emails/month, Pro tier: 25,000 emails/month. Limits reset monthly.

🚫 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.

❌ File Too Large

Error: File is too large. Maximum allowed size is 5MB.

Solution: Maximum file size is 5MB per file. 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:

🔒 Pro Tier Required

Error: File uploads require Pro tier

Solution: File uploads are only available for Pro tier accounts. Upgrade your plan to enable file uploads.

🚫 429 Too Many Requests

Error: Rate limit exceeded

For Form Submissions: You've exceeded your monthly email limit. Check your usage in the dashboard and wait for the monthly reset or upgrade your plan.

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 tier limits reset monthly, and Pro tier has higher limits.

❌ 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

❌ ALTCHA Challenge Not Loading

Check:

• ALTCHA script is loaded: altcha.min.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.