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 rate limit is set automatically based on your plan (Agency: 300/min, Enterprise: 600/min).

ℹ️

Rate limits are tracked per API key, not per IP. Rate limits are platform-managed based on your plan and cannot be changed by users.

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