Error Handling

The Formstamper API uses standard HTTP status codes and returns consistent error response formats.

HTTP Status Codes

Code	Meaning	When Used
200	OK	Request succeeded
201	Created	Resource created successfully
202	Accepted	Request accepted for async processing (webhooks)
400	Bad Request	Invalid input, validation error, malformed JSON
401	Unauthorized	Missing or expired authentication token
403	Forbidden	Valid auth, but insufficient permissions
404	Not Found	Resource doesn't exist
409	Conflict	Resource already exists (e.g., duplicate email)
423	Locked	Account is disabled
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server error

Error Response Format

Most error responses include a descriptive message:

{
  "error": "Bad Request",
  "message": "Payload validation failed: missing required field 'tenant_name'",
  "status": 400
}

For validation errors, additional field-level details may be included:

{
  "error": "Validation Failed",
  "message": "Invalid input",
  "status": 400,
  "fieldErrors": [
    {
      "field": "email",
      "message": "must be a valid email address"
    },
    {
      "field": "password",
      "message": "must be at least 8 characters"
    }
  ]
}

Common Error Scenarios

Authentication Errors

Scenario	Status	Message
No token provided	401	Missing or invalid token
Expired access token	401	Token has expired
Invalid refresh token	401	Invalid refresh token
Account not verified	403	Email not verified
Account locked	423	Account is disabled
2FA required	200	Returns requires2FA: true

Permission Errors

Scenario	Status	Message
Non-admin accessing admin endpoints	403	Access denied
Accessing another user's workflow	403	You do not have permission
Org member editing org settings	403	Insufficient role

Resource Errors

Scenario	Status	Message
Template not found	404	Template not found
Workflow not found	404	Workflow not found
Webhook for unknown workflow	404	Workflow not found!
Duplicate email registration	409	Email already registered

Rate Limiting

When rate limited, the response includes retry headers:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1712930400

Best Practices

:::tip Error Handling Tips

1. Always check the status code before parsing the response body.
2. Implement token refresh logic — when you get a 401, try refreshing the access token before retrying.
3. Handle rate limits gracefully — respect the Retry-After header and implement exponential backoff.
4. Log error responses — include the full error message for debugging.
5. Validate on the client side — catch obvious errors (empty fields, invalid emails) before sending API requests. :::