.png){kind=logo}
PluginReference
Error codes
Every machine-readable error the Plugin API returns, grouped by where you will meet it, with what to check.
Every failure uses the same envelope. The code is in result.error; validation failures use errors keyed by field instead.
{
"message": "This origin is not allowed for this plugin",
"result": { "error": "origin_not_allowed", "origin": "https://staging.customer.com" }
}Where to see them
- In the editor. When the editor cannot start it shows "Plugin editor unavailable". Open your browser's network tab and read the
sessionresponse. - From your server. Backend API responses carry the code directly.
- In the dashboard. Failures show as form messages on the settings tabs.
Session errors
Returned by the session endpoint when the editor starts.
| Status | error | What to check |
|---|---|---|
| 403 | origin_not_allowed | The page's origin is not on the allowed domains. Scheme and port must match exactly |
| 403 | origin_required | The request had no usable origin |
| 401 | invalid_plugin | Unknown plugin id, inactive plugin, or wrong secret. Check the Plugin ID on the General tab |
| 403 | identity_signature_required | Plugin is in signed mode and the URL carries no signature. See identity signing |
| 401 | identity_signature_invalid | Payload built differently or wrong secret. Rebuild the payload exactly and count bytes |
| 401 | identity_signature_expired | identity_expires is in the past. Sign when the page loads, not at build time |
| 422 | identity_expires_out_of_range | More than 15 minutes ahead, or milliseconds instead of seconds |
| 403 | browser_sessions_disabled | Plugin is in backend identity mode |
| 402 | quota_exceeded | Plan's users allowance is spent and this is a new user. Upgrade the plan |
| 422 | origin_invalid | The origin field in a server-side session request is malformed |
| 422 | A secret was sent from a browser, or external_user_id starts with anon: | |
| 429 | Rate limited. 10 per minute per plugin and IP |
Errors during a session
| Status | error | What to check |
|---|---|---|
| 401 | invalid_token | Session expired or revoked. The editor renews automatically; reload if it persists |
| 403 | origin_mismatch | Token used from an origin other than the one it was issued for |
| 404 | template_not_found | No such template, another user's, another plugin's, or a gallery template outside curation. Check template_id belongs to the same external_user_id |
| 402 | quota_exceeded | A metered allowance is used up. result.feature names it: users, ai_generations, image_storage |
| 402 | feature_not_in_plan | Version history, the template gallery or the module library on a plan without it. result.feature names it |
| 409 | plugin_not_provisioned | Plugin is still being set up. Retry shortly |
| 409 | storage_not_public | Custom storage has no public_url. Set it on the Custom Storage tab |
| 404 | image_not_found | Not this user's image, or no such uuid |
| 422 | unsupported_image_property | Only used_in_banner can be set |
| 403 | ai_not_configured | No AI key on the plugin. Add one on the AI Credentials tab |
| 403 | no_ai_credential | A key exists but could not be read. Save it again |
| 502 | ai_generation_failed | The provider refused or was unreachable. Check the key and the provider's status |
| 502 | stock_provider_unavailable | The stock provider refused or was unreachable. Usually a bad or expired key, or its hourly limit. Check it on the Stock Images tab |
| 422 | invalid_download_location | The tracked URL is not one that provider accepts. Send the download_location from the image object unchanged |
| 422 | invalid_stock_url | Import was given a URL that is not on a Pixabay host. Unsplash and Pexels images are used by URL, never imported |
| 502 | stock_import_failed | The Pixabay download failed, or the file was empty or over 10 MB |
Backend API errors
| Status | error | What to check |
|---|---|---|
| 401 | credentials_required | Send both X-Plugin-Id and X-Plugin-Secret |
| 401 | invalid_credentials | Wrong secret, unknown plugin, or suspended plugin |
| 401 | credentials_in_query | Credentials must be headers, never query parameters |
| 409 | plugin_not_provisioned | Retry shortly |
| 404 | template_not_found | The id does not belong to this plugin |
| 429 | 60 per minute or 2000 per day exceeded. Honour Retry-After |