Error Codes

API error responses and troubleshooting

HTTP Status Codes

Status	Description
200	Success
201	Created
400	Bad request (validation error)
401	Unauthorized (invalid API key)
403	Forbidden (form disabled, domain not allowed)
404	Not found
429	Rate limit exceeded
500	Server error

Error Response Format

{
  "error": "Human-readable error message",
  "code": "ERROR_CODE"
}

Common Errors

Form Submission Errors

Error	Cause	Solution
Form not found	Invalid form slug	Check the form slug in your URL
Form is disabled	Form deactivated	Enable form in dashboard
Domain not allowed	Origin not in allowed list	Add domain to form settings
reCAPTCHA verification required	Missing captcha token	Include reCAPTCHA response
reCAPTCHA verification failed	Invalid token	Ensure valid reCAPTCHA setup
Please use a work email	Free email blocked	Use company email address
File uploads not enabled	Files sent to non-upload form	Enable file uploads in settings
Storage quota exceeded	Account storage full	Upgrade plan or delete files

API Errors

Error	Cause	Solution
Unauthorized	Missing or invalid API key	Check Authorization header
Forbidden	Insufficient permissions	Use key with correct permissions
Rate limit exceeded	Too many requests	Wait and retry, or upgrade plan

Rate Limiting

When rate limited, the response includes:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640000060
Retry-After: 60

Wait until X-RateLimit-Reset timestamp or Retry-After seconds before retrying.

Debugging Tips

1. Check the error field for specific details
2. Verify your API key has required permissions
3. Ensure Content-Type header matches body format
4. For form submissions, add Accept: application/json to get JSON errors