Errors

All errors return a JSON response with an error message and HTTP status code.

Error Codes

400 Bad Request

Missing or invalid parameters in your request.

{
  "error": "Missing required field: formId"
}

Common causes:

Missing apiKey, formId, or payload
Empty payload object
Invalid formId format
Payload exceeds 100KB size limit

401 Unauthorized

Invalid or missing API key.

{
  "error": "Invalid API key"
}

Common causes:

Incorrect API key
API key has been revoked
API key from a different account

429 Too Many Requests

Rate limit exceeded. Check the response headers for reset timing.

{
  "error": "Rate limit exceeded",
  "retryAfter": 60
}

Response headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Unix timestamp when the limit resets

See Rate Limiting for details.

500 Internal Server Error

An unexpected error occurred on our side.

{
  "error": "Internal server error"
}

These are rare. If persistent, submit a request at https://www.formsentry.ai/contact with details of your request and the error.

Retry Strategy

For 429 and 500 errors, implement exponential backoff:

async function verifyWithRetry(data, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    const response = await fetch('https://api.formsentry.ai/v1/verify', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(data)
    });

    if (response.ok) return response.json();

    if (response.status === 429 || response.status >= 500) {
      const delay = Math.min(1000 * Math.pow(2, attempt - 1), 5000);
      await new Promise(resolve => setTimeout(resolve, delay));
      continue;
    }

    // 400, 401 — don't retry, fix the request
    throw new Error(`API error: ${response.status}`);
  }
  throw new Error('Max retries exceeded');
}

Key points:

Retry 429 and 5xx errors only
Don’t retry 400 or 401 — these require fixing the request
Use exponential backoff (1s, 2s, 4s)
Set a maximum of 3 retries
Set a request timeout of 5 seconds