Error Reference

Complete reference for Formfex API error responses, rate limit details, and troubleshooting

Overview

When an API request fails, Formfex returns a structured JSON error response. This page documents all error types, their meanings, and recommended actions.

Error Response Format

Standard Error Response

Every error response follows the same base structure:

json

{
  "message": "Human-readable error description",
  "data": null,
  "error": "ERROR_CODE"
}

Field	Type	Description
`message`	`string`	Translated error message (based on `Accept-Language` header)
`data`	`null`	Always `null` for error responses
`error`	`string`	HTTP status name (e.g., `TOO_MANY_REQUESTS`, `UNAUTHORIZED`)

Rate Limit Error Response (429)

Rate limit errors include an additional rate_limit field with structured details:

json

{
  "message": "You've exceeded the API rate limit. Check the rate_limit field in the response body for details on when you can retry.",
  "data": null,
  "error": "TOO_MANY_REQUESTS",
  "rate_limit": {
    "type": "BURST_LIMIT",
    "retry_after": 45,
    "limit": 200,
    "remaining": 0,
    "reset": 1710000000
  }
}

Field	Type	Description
`rate_limit.type`	`string`	One of: `BURST_LIMIT`, `HOURLY_LIMIT`, `MONTHLY_QUOTA`, `AI_ENDPOINT_LIMIT`
`rate_limit.retry_after`	`number`	Seconds to wait before retrying
`rate_limit.limit`	`number`	The limit that was exceeded
`rate_limit.remaining`	`number`	Remaining requests (always `0` when rate limited)
`rate_limit.reset`	`number`	Unix timestamp (seconds) when the limit window resets

Rate Limit Errors (429)

BURST_LIMIT

You sent too many requests in a short burst (per-minute limit exceeded), but your hourly quota still has capacity.

When it occurs: You exceeded the per-minute request limit (e.g., 20/min on Starter, 60/min on Pro).

Recommended action: Wait for the number of seconds in retry_after (typically under 60 seconds), then resume. Consider adding a small delay between requests.

HOURLY_LIMIT

You've exhausted your hourly request quota.

When it occurs: You used all allowed requests for the current hour window (e.g., 200/hr on Starter, 1000/hr on Pro).

Recommended action: Wait until the reset timestamp. If you frequently hit this limit, consider upgrading your plan or optimizing your request patterns.

MONTHLY_QUOTA

Your monthly API call quota is exhausted for the current billing period.

When it occurs: You used all API calls in your 30-day billing period (e.g., 2,000 on Starter, 20,000 on Pro).

Recommended action: Upgrade your plan for a higher monthly quota. Alternatively, wait until the reset timestamp when your billing cycle renews.

AI_ENDPOINT_LIMIT

You've hit the per-endpoint hourly rate limit on an AI-powered endpoint.

When it occurs: You exceeded the hourly limit for a specific AI endpoint (Generate Form, Smart Analytics, or Analytics Chat). These limits are separate from the general API rate limits.

Recommended action: Wait until the reset timestamp. AI endpoints have independent rate limit windows — hitting the limit on one endpoint does not affect others.

Authentication Errors

401 Unauthorized

Common causes:

Missing or malformed Authorization header
API key has been revoked
API key has expired
API key rotation deadline has passed without completing rotation

Fix: Verify your API key is correct and active. Generate a new key from the dashboard if needed.

403 Forbidden

Common causes:

API key lacks the required scope for the endpoint (e.g., calling a write endpoint with a read-only key)
Your plan does not include Public API access

Fix: Check the required scopes for the endpoint you're calling. Create a new API key with the appropriate scopes, or upgrade your plan.

Common Error Codes

HTTP Status	`error` Field	Description
400	`BAD_REQUEST`	Invalid request body or query parameters
401	`UNAUTHORIZED`	Missing, invalid, or expired API key
403	`FORBIDDEN`	Valid key but insufficient permissions or plan
404	`NOT_FOUND`	Requested resource does not exist
429	`TOO_MANY_REQUESTS`	Rate limit or quota exceeded (see `rate_limit` field)
500	`INTERNAL_SERVER_ERROR`	Unexpected server error

Troubleshooting

Use the rate_limit field

When you receive a 429 response, always read the rate_limit object in the response body. The type field tells you which limit you hit, and retry_after tells you exactly how long to wait.

Monitor headers proactively

Every successful response includes X-RateLimit-Remaining and X-Monthly-Used headers. Monitor these to slow down before hitting a limit.

Don't retry immediately on MONTHLY_QUOTA

Unlike burst and hourly limits (which reset in seconds or minutes), a monthly quota reset can be days away. Implement logic to detect MONTHLY_QUOTA and alert your team or trigger a plan upgrade instead of blindly retrying.

Localized messages

Error messages are translated based on the Accept-Language header (en or tr). The rate_limit field values are always consistent regardless of language.

PreviousRate Limits NextOverview