Errors

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

Error format


{
  "error": "No form with ID abc123 exists in your account.",
  "code": "not_found"
}

Field	Type	Description
`error`	string	Human-readable description
`code`	string	Machine-readable error identifier

HTTP status codes

Status	Meaning
`200 OK`	Request succeeded
`400 Bad Request`	Invalid request parameters
`401 Unauthorized`	Missing or invalid API key
`403 Forbidden`	Plan restriction or insufficient access
`404 Not Found`	Resource does not exist
`429 Too Many Requests`	Rate limit exceeded
`500 Internal Server Error`	Unexpected server error

Error codes

Code	Status	Description
`unauthorized`	401	API key missing or malformed
`plan_required`	403	API access requires Starter or Pro plan
`forbidden`	403	Valid key but insufficient permissions
`not_found`	404	Resource does not exist or does not belong to your account
`bad_request`	400	Invalid request (e.g. unrecognized parameter)
`invalid_cursor`	400	Pagination cursor is malformed or expired
`invalid_limit`	400	`limit` must be a positive integer
`rate_limited`	429	Too many requests. See Rate Limits.
`method_not_allowed`	405	HTTP method not supported on this endpoint
`internal_error`	500	Unexpected error on our end

Handling errors


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