Errors

The Formtorch API uses standard HTTP status codes and returns a consistent JSON error body.

Error format


{
  "error": {
    "code": "form_not_found",
    "message": "No form with ID abc123 exists in your account.",
    "status": 404
  }
}

Field	Type	Description
`code`	string	Machine-readable error identifier
`message`	string	Human-readable description
`status`	number	HTTP status code (same as response status)

HTTP status codes

Status	Meaning
`200 OK`	Request succeeded
`201 Created`	Resource was created
`204 No Content`	Request succeeded, no body returned
`400 Bad Request`	Invalid request parameters
`401 Unauthorized`	Missing or invalid API key
`403 Forbidden`	Valid key but insufficient permissions
`404 Not Found`	Resource does not exist
`409 Conflict`	Request conflicts with current state
`422 Unprocessable Entity`	Validation failed
`429 Too Many Requests`	Rate limit exceeded
`500 Internal Server Error`	Unexpected server error

Common error codes

Code	Status	Description
`unauthorized`	401	API key missing or invalid
`forbidden`	403	Key does not have access to this resource
`form_not_found`	404	Form ID does not exist
`submission_not_found`	404	Submission ID does not exist
`validation_error`	422	One or more fields failed validation
`rate_limit_exceeded`	429	Too many requests. See Rate Limits.
`internal_error`	500	Unexpected error on our end

Handling errors


const res = await fetch("https://api.formtorch.com/v1/forms/abc123", {
  headers: { Authorization: `Bearer ${process.env.FORMTORCH_API_KEY}` },
});
 
if (!res.ok) {
  const { error } = await res.json();
  console.error(`[${error.code}] ${error.message}`);
  // handle by code
}

Validation errors

For 422 responses, the error body includes a fields array with per-field details:


{
  "error": {
    "code": "validation_error",
    "message": "Validation failed.",
    "status": 422,
    "fields": [
      { "field": "name", "message": "Name is required." },
      { "field": "email", "message": "Must be a valid email address." }
    ]
  }
}