Errors

When a form submission fails, Formoar returns an appropriate HTTP status code and a JSON error response. This page documents all possible error responses so you can handle them gracefully.

For HTML form submissions (non-AJAX), errors are shown on a default Formoar error page. For JSON submissions, you'll receive the structured error response documented below.

Error response format

All error responses follow this structure:

Error response

{
  "success": false,
  "error": "Human-readable error message"
}

Status codes

Name
200 OK
Description
The submission was accepted successfully.
Name
400 Bad Request
Description
The request body could not be parsed, or a required field was missing.
Name
403 Forbidden
Description
The submission was blocked — the origin is not in the allowed origins list, or spam was detected.
Name
404 Not Found
Description
The form ID doesn't exist or the form has been deactivated.
Name
429 Too Many Requests
Description
Rate limit exceeded (per-IP) or monthly submission limit exceeded (per-plan).
Name
500 Internal Server Error
Description
An unexpected error occurred on the server.

Error types

Validation errors

These errors indicate a problem with the request itself.

Name
Invalid form ID
Description
The form ID in the URL is not a valid UUID format.
Name
Form not found
Description
No form exists with the provided ID, or the form has been deactivated.
Name
Empty submission
Description
The request body contained no data fields.

Validation error

{
  "success": false,
  "error": "Form not found"
}

Security errors

These errors are returned when a submission is blocked for security reasons.

Name
Origin not allowed
Description
The request came from a domain not in the form's allowed origins list.
Name
Spam detected
Description
The honeypot field was not empty, indicating a bot submission.
Name
Turnstile verification failed
Description
The Cloudflare Turnstile token was invalid or expired.

Security error

{
  "success": false,
  "error": "Origin not allowed"
}

Limit errors

These errors occur when rate limits or plan quotas are exceeded.

Name
Rate limit exceeded
Description
Too many submissions from the same IP address (max 5 per minute).
Name
Monthly submission limit exceeded
Description
Your plan's monthly submission quota has been reached. Upgrade your plan to continue accepting submissions.

Limit error

{
  "success": false,
  "error": "Monthly submission limit exceeded"
}