Errors & Rate Limits

How ProForms communicates errors and enforces rate limits.

Error Format

All errors follow a consistent JSON structure:

Error Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Form name is required",
    "details": {
      "issues": [
        {
          "path": [
            "name"
          ],
          "message": "Required"
        }
      ]
    }
  }
}

Error Codes

HTTP	Code	Meaning
400	VALIDATION_ERROR	Invalid request body or parameters
400	INVALID	General bad request
401	UNAUTHORIZED	Missing or invalid authentication
403	FORBIDDEN	Valid auth but insufficient role
403	INSUFFICIENT_PERMISSION	Missing required permission
404	NOT_FOUND	Resource doesn't exist or you don't have access
409	CONFLICT	Resource already exists
429	RATE_LIMITED	Too many requests — slow down
500	SERVER_ERROR	Something went wrong on our end

Rate Limits

API keys are rate-limited per minute. The default is 60 requests/minute, configurable up to 1,000.

ℹ️

Rate limits are tracked per API key, not per IP. If you need higher limits, create your key with a higher rateLimitPerMin value (max 1,000).

Handling Errors

Best practices for error handling:

•Always check the success field before reading data
•Use the error.code for programmatic handling, not the message
•On 429, wait at least 60 seconds before retrying
•On 500, retry with exponential backoff