Error Codes
All RizzForms API errors return a consistent JSON structure. Use the
error field for programmatic handling and the
message field for human-readable details.
Error Format
Every error response follows this shape:
{
"ok": false,
"error": "error_code",
"message": "A human-readable description of what went wrong.",
"links": [
{ "rel": "docs", "href": "https://forms.rizzness.com/docs/api-reference/errors" }
]
}
The links array provides HATEOAS-style navigation hints. It
may include links to documentation, the current resource, or related
endpoints.
not_found — 404
The requested resource does not exist. This applies to forms looked up by
endpoint_token, submissions by ID, and plugins by ID.
{
"ok": false,
"error": "not_found",
"message": "The requested resource could not be found."
}
How to fix: Double-check the endpoint_token
or resource ID in the URL. Use GET /api/forms to list your
forms and verify token values.
not_active — 404
The form exists but has been deactivated. Submissions to inactive forms are rejected.
{
"ok": false,
"error": "not_active",
"message": "This form is not currently active."
}
How to fix: Reactivate the form from the dashboard, or
send PATCH /api/forms/:id with
{"is_active": true}.
unauthorized — 401
No API key was provided in the request. All /api/ endpoints
require authentication.
{
"ok": false,
"error": "unauthorized",
"message": "No API key provided. Include an Authorization: Bearer header."
}
How to fix: Add the header
Authorization: Bearer frk_... to your request. See
Authentication.
invalid_api_key — 401
An API key was provided but does not match any active key in the system.
{
"ok": false,
"error": "invalid_api_key",
"message": "The provided API key does not match any active key."
}
How to fix: Check for typos in the key value. Make sure
you are using the full key including the frk_ prefix. If the
key was revoked, generate a new one from the dashboard.
forbidden — 403
The API key is valid but lacks the required permission scope for the requested action.
{
"ok": false,
"error": "forbidden",
"message": "Your API key does not have the required permission for this action."
}How to fix: Use an Admin API key, or create a new key with the needed scope. See Permissions & Roles for scope details.
invalid_config — 422
The plugin configuration failed validation. Common causes include non-HTTPS URLs, private/internal IP addresses, or missing required fields.
{
"ok": false,
"error": "invalid_config",
"message": "Webhook URL must use HTTPS and not point to a private IP address."
}
How to fix: Ensure the webhook URL starts with
https:// and resolves to a public IP address. Private
ranges (10.x, 172.16-31.x, 192.168.x) and localhost are rejected.
unsupported_plugin — 422
The API currently supports creating webhook plugins only.
Other plugin types (Slack, email, Google Sheets, etc.) must be configured
through the dashboard.
{
"ok": false,
"error": "unsupported_plugin",
"message": "Only 'webhook' plugins can be created via the API."
}
How to fix: Set plugin_type to
"webhook" in your request body. For other integrations,
use the RizzForms dashboard.