Errors
Every Plenary API error has the same JSON shape: an error object with a stable, machine-readable code and, for some codes, a vars object with details. Branch on code, never on message text; the API sends no human-readable message. This page lists every code the server can return.
Error envelope
Section titled “Error envelope”{ "error": { "code": "entry_field_required", "vars": { "field": "title" } }}| Field | Type | Meaning |
|---|---|---|
error.code |
string | A lowercase, underscore-separated code, such as entry_slug_taken. Stable across releases. |
error.vars |
object, optional | Values that explain the error, such as the offending field, an index into an array you sent, or a reason from a provider. Present only when the code has details. |
There is no list of errors: the API stops at the first problem it finds and reports that one. Fix it and send the request again to find the next.
Two responses are not in this shape: a 401/403 from a proxy in front of Plenary, and a plain-text 500 if the server cannot encode its response. Treat any non-JSON error body as a transport problem.
HTTP status codes
Section titled “HTTP status codes”| Status | Meaning in Plenary |
|---|---|
400 |
The request is malformed: bad JSON, a bad query parameter, a missing confirmation parameter. |
401 |
No credential, or the credential is invalid, expired, or revoked. |
403 |
The credential is valid but not allowed: missing grant, public key on a private route, origin not allowed, a Free plan limit, or a Cloud-managed setting. |
404 |
The resource does not exist, or you may not know it exists (a private model to a public key, an entry on a site you cannot read). |
409 |
Conflict with existing data: a key or slug is taken, or something still uses what you are deleting. |
413 |
The body or upload is too large. |
415 |
Wrong Content-Type. |
422 |
The request is well-formed but the values are invalid. |
429 |
Rate limited. |
500 |
Server error. Details are in the server log. |
502 |
An upstream provider refused a test message (test_send_failed). |
503 |
Returned by GET /api/v1/health when the database is unreachable. |
Handle errors in the SDK
Section titled “Handle errors in the SDK”@plenary/client throws a PlenaryError for every non-2xx response, with status, code, and vars. Subclasses let you branch on the common statuses:
| Class | Status |
|---|---|
PlenaryNotFoundError |
404 |
PlenaryForbiddenError |
403 |
PlenaryValidationError |
400 and 422 |
PlenaryError |
Everything else |
When the body is not the error envelope, code is http_<status>, for example http_502.
import { notFound } from "next/navigation";import { createClient, PlenaryNotFoundError } from "@plenary/client";
const plenary = createClient({ baseUrl: process.env.PLENARY_BASE_URL!, siteKey: process.env.PLENARY_SITE_KEY!, apiKey: process.env.PLENARY_API_KEY!, locale: "en-us",});
export default async function Page({ params }: { params: Promise<{ slug: string }> }) { const { slug } = await params; try { const post = await plenary.getEntry("blog_post", slug); return <h1>{post.title}</h1>; } catch (err) { if (err instanceof PlenaryNotFoundError) notFound(); throw err; }}For form submissions, check err.code and err.vars.field to show the message next to the right input. See the client SDK reference.
Errors in the CLI
Section titled “Errors in the CLI”The CLI prints the code, the status, and each vars entry to stderr and exits with code 1:
plenary: role_in_use (HTTP 409) users: 1Codes by area
Section titled “Codes by area”Some codes appear with two statuses: the one that applies depends on the route.
General
Section titled “General”| Code | HTTP | Meaning |
|---|---|---|
invalid_json_body |
400 | The request body is not valid JSON, or a field has the wrong JSON type. |
invalid_content_type |
415 | The request needs Content-Type: application/json (or multipart/form-data for uploads). |
invalid_request |
400 | The request is missing a required value or is malformed. |
not_found |
404 | The resource the route targets does not exist. Returned before the permission check. |
internal_server_error |
500 | An unexpected server error. Details are in the server log, never in the response. |
Authentication and access
Section titled “Authentication and access”| Code | HTTP | Meaning |
|---|---|---|
authentication_required |
401 | No credential was sent, or the user session no longer exists. Send X-API-KEY or Authorization: Bearer. |
token_invalid |
401 | The bearer access token is malformed, has a bad signature, or has expired. Refresh it. |
api_key_invalid |
401 | The API key is unknown, inactive, revoked, or expired. The response does not say which. |
api_key_origin_not_allowed |
403 | The request’s Origin is not in the key’s allowed origins. |
rate_limited |
429 | Too many requests: the API key’s per-minute limit, or the sign-in limit for this IP address. |
permission_denied |
403 | The credential is valid but holds no grant for this action on this site or model, or the route is for super users only. On a metadata import, vars lists the denied models, roles, and sites. |
forbidden |
403 | An API key reached a route that only a signed-in user may call. |
unauthorized |
401 | No authenticated principal on a route that needs one. |
cloud_managed |
403 | This setting is managed by Plenary Cloud and cannot be read or changed on the instance. |
Sign-in and sessions
Section titled “Sign-in and sessions”| Code | HTTP | Meaning |
|---|---|---|
invalid_credentials |
401 | Wrong identifier or password, an inactive account, or a two-factor account with no usable code destination. |
sso_required |
403 | Single sign-on is required on this instance and the identifier is not a super user’s. Sign in through the identity provider. |
refresh_token_required |
400 | POST /auth/refresh or /auth/logout was called without refresh_token. |
refresh_token_invalid |
401 | The refresh token is unknown or malformed. |
session_expired |
401 | The refresh token has expired. Sign in again. |
session_revoked |
401 | The refresh token was revoked, or an already-used token was presented again, which revokes the whole session. |
otp_challenge_invalid |
400 | The challenge_id is malformed or unknown. |
otp_challenge_expired |
401 | The sign-in challenge has expired. Start again from the password step. |
otp_challenge_locked |
401 | Too many wrong codes for this challenge. Start again from the password step. |
otp_session_expired |
401 | The challenge no longer exists. Start again from the password step. |
otp_method_required |
400 | otp_method is missing. Use email or sms. |
otp_method_invalid |
400 | otp_method is not email or sms. |
otp_email_unavailable |
400 | The account has no verified email address to send a code to. |
otp_sms_unavailable |
400 | The account has no verified phone number, or SMS sending is not configured. |
otp_not_sent |
400 | No code has been sent for this challenge yet. Call /auth/login/otp/send first. |
otp_invalid |
401 | The code is wrong. |
otp_expired |
401 | The code has expired (codes last 10 minutes). Send a new one. |
otp_rate_limited |
429 | Codes were requested too often for this challenge. |
otp_sms_cooldown |
429 | A text message went to this account less than a minute ago. vars.retry_after is the seconds to wait. |
otp_sms_throttled |
429 | Five text messages went to this account in the last hour. vars.retry_after is the seconds to wait; an administrator can reset the limit from User Management. |
otp_send_failed |
500 | The email or SMS provider could not send the code. |
passkey_unsupported |
400 | The instance has no server.public_url, so it cannot act as a passkey relying party. Every passkey route answers this. |
passkey_session_invalid |
400 | The passkey ceremony’s session_id is missing, unknown, older than 5 minutes, or already used. Request new options and try again. |
passkey_invalid |
401 | On sign-in, the passkey could not be verified or the account is inactive; the response does not say which. On enrolment (400), the browser’s response did not verify against the options issued. |
passkey_name_required |
422 | A passkey’s name is empty or longer than 64 characters. |
passkey_already_registered |
409 | The credential is already enrolled, on this account or another. |
passkey_not_found |
404 | No passkey with that id on this account (or, for an administrator, on that user). |
password_reset_required_fields |
400 | reset_id, new_password, and confirm_password are required. |
password_mismatch |
422 | new_password and confirm_password differ. |
invalid_reset_id |
422 | The password reset link is unknown, used, or expired. |
email_verify_required_fields |
400 | POST /auth/email-verify needs its verification id. |
invalid_verify_id |
422 | The email confirmation link is unknown, used, or expired, or the account’s address has changed since. |
Single sign-on
Section titled “Single sign-on”Codes on the sign-in page arrive as ?error=<code> on the redirect back from the identity provider; see Single sign-on.
| Code | HTTP | Meaning |
|---|---|---|
sso_provider_not_found |
404 | GET /auth/sso/{key}/start with a key that is not the configured protocol (oidc or saml), or the SAML metadata route while SAML is not configured. |
sso_provider_disabled |
404 | The connection exists but is switched off. |
sso_code_invalid |
401 | The one-time login code is unknown, already used, expired (60 seconds), or presented from a different IP address. Start the sign-in again. |
sso_user_inactive |
401 | The account is deactivated. On the exchange, it was deactivated after the provider callback. |
sso_state_invalid |
redirect | The sign-in took too long (10 minutes), was already completed, or the connection changed mid-flow. Start again. |
sso_idp_error |
redirect | The identity provider refused or failed the sign-in, or could not be reached. The provider’s own message is in the server log. |
sso_token_invalid |
redirect | The provider’s response did not verify: bad signature, nonce mismatch, expired, or unsigned. |
sso_idp_initiated_unsupported |
redirect | A SAML response that answers no request from Plenary. Start the sign-in from Plenary’s sign-in page. |
sso_email_unverified |
redirect | The asserted email matches an account, but the provider did not vouch for the address, so it cannot be linked. |
sso_email_domain_not_allowed |
redirect | The email’s domain is not in the connection’s allowed domains. |
sso_user_not_linked |
redirect | No account is linked to this identity and the connection does not create accounts, or the matching account is linked to a different identity. |
sso_user_required_fields |
redirect | The provider did not supply an email, first name, and last name for a new account. |
Passwords
Section titled “Passwords”| Code | HTTP | Meaning |
|---|---|---|
password_too_short |
422 | The new password is shorter than 8 characters. |
password_missing_uppercase |
422 | The new password has no uppercase letter. |
password_missing_lowercase |
422 | The new password has no lowercase letter. |
password_missing_digit |
422 | The new password has no digit. |
password_incorrect |
422 | current_password is wrong (also returned for an account with no password). |
Licensing
Section titled “Licensing”| Code | HTTP | Meaning |
|---|---|---|
license_missing |
422 | The install request’s license is empty. |
license_malformed |
422 | The license token is damaged or inconsistent. |
license_unsupported_version |
422 | The license format is newer than this server understands. Upgrade Plenary. |
license_unknown_key |
422 | The license was signed with a key this server does not know. |
license_signature_invalid |
422 | The license signature does not verify; the token was altered or truncated. |
license_host_mismatch |
422 | The license does not permit this server’s public_url hostname. |
license_expired |
422 | The evaluation license has expired. |
license_update_window_exceeded |
422 | This release is newer than the license’s update window. |
license_limit_sites |
403 | Creating this site would exceed the Free plan’s one site. vars.limit, vars.count. |
license_feature_forms |
403 | Forms are not included in the Free plan. On a metadata import, vars.forms names the files. |
license_feature_sso |
403 | Single sign-on is not included in the Free plan. |
license_managed_externally |
409 | The active license comes from PLENARY_LICENSE or license.file and cannot be replaced through the API. vars.source is env or file. |
Content entries
Section titled “Content entries”| Code | HTTP | Meaning |
|---|---|---|
entry_id_invalid |
400 | The entry id in the path is not a valid id. |
entry_not_found |
404 | No such entry, or it is on a site you cannot read. |
entry_model_not_content |
404 / 422 | The model is a form or an object, which has no content entries. Use the Forms API for forms. |
entry_model_not_in_site |
422 | A restored revision names a model on another site. Only revisions recorded before each model belonged to one site can. |
entry_site_key_required |
422 | site_key is required to create an entry. |
entry_locale_invalid |
400 / 422 | locale is not a valid locale code. |
entry_locale_not_allowed |
422 | locale is not one of the site’s locales. |
entry_slug_taken |
409 | Another entry of this model already uses the slug on this site and locale. |
entry_field_value_taken |
409 | A field marked unique already has this value on another entry. vars.field. |
entry_singleton_exists |
409 | The model is a singleton and already has its entry for this site and locale. |
entry_field_unknown |
422 | fields contains a key the model does not define. vars.field. |
entry_field_required |
422 | A required field is missing. vars.field. |
entry_field_required_nonempty |
422 | A required field is present but empty. vars.field. |
entry_field_value_required |
422 | A field was sent with no value. vars.field. |
entry_field_computed_read_only |
422 | A computed field was sent; computed values are produced by the server. vars.field. |
entry_field_schema_invalid |
422 | A field value has the wrong shape for its type. vars.field, vars.path, vars.message. |
entry_field_rule_violation |
422 | A field value breaks a validation rule. vars.field, vars.name, vars.rule (for example phone_invalid, country_not_allowed, color_not_allowed, color_alpha_not_allowed) and any rule-specific values. |
entry_list_item_schema_invalid |
422 | An item in a list field has the wrong shape. vars.field, vars.index, vars.path, vars.message. |
entry_list_item_invalid |
422 | An item in a list field is not an object of the expected shape. |
entry_list_subfield_unknown |
422 | A list item contains a key its schema does not define. |
entry_list_subfield_required |
422 | A list item is missing a required sub-field. |
entry_list_subfield_required_nonempty |
422 | A list item has a required sub-field that is empty. |
entry_list_subfield_computed_read_only |
422 | A list item sends a computed sub-field. |
entry_list_subfield_schema_invalid |
422 | A list item’s sub-field has the wrong shape. |
entry_list_subfield_rule_violation |
422 | A list item’s sub-field breaks a validation rule. |
entry_object_field_invalid |
422 | An object field’s value is not an object. |
entry_subfield_unknown |
422 | An object field contains a key its schema does not define. |
entry_subfield_required |
422 | An object field is missing a required sub-field. |
entry_subfield_required_nonempty |
422 | An object field has a required sub-field that is empty. |
entry_subfield_computed_read_only |
422 | An object field sends a computed sub-field. |
entry_subfield_schema_invalid |
422 | An object field’s sub-field has the wrong shape. |
entry_subfield_rule_violation |
422 | An object field’s sub-field breaks a validation rule. |
entry_dom_invalid |
422 | A Page Builder field’s document is invalid. vars.reason. |
entry_note_required |
422 | The model has Require Change Notes on and no note was sent. |
entry_note_too_long |
422 | The revision note is too long. vars.max. |
entry_publish_at_past |
422 | publish_at is in the past. |
entry_unpublish_at_past |
422 | unpublish_at is in the past. |
entry_always_published |
409 | The model is always published, so its entries cannot be scheduled or unpublished. |
entry_draft_pending |
409 | The entry has pending changes, so an unpublish needs ?draft=merge or ?draft=discard. |
entry_draft_choice_invalid |
400 | ?draft= on an unpublish is neither merge nor discard. vars.draft. |
entry_draft_not_found |
404 | A discard of pending changes on an entry that has none. |
entry_folder_not_found |
422 | folder_id names no folder of this model on this site. |
entry_folder_translation_mismatch |
422 | Translations of an entry share one folder; the requested folder differs from the other translations’. |
entry_move_ids_required |
422 | A bulk move was sent without entry ids. |
entry_move_entry_not_found |
422 | Some entries in a bulk move do not exist. vars.ids. |
entry_referenced |
409 | The entry cannot be deleted because other entries reference it through a reference that forbids deletion. vars.blocked lists them. |
entry_transformer_rejected |
422 | A transformer refused the write on purpose. vars.transformer, vars.message, and vars.field when it names one. |
entry_transformer_failed |
422 | A transformer threw an error. vars.transformer, vars.message, and vars.line, vars.column when known. |
entry_transformer_timeout |
422 | A transformer ran too long. vars.transformer, vars.message. |
restore_model_missing |
422 | The revision’s model has been deleted, so the entry cannot be restored. |
revision_model_not_restorable |
422 | The revision belongs to a model, not an entry. Model history is read-only. |
Entry queries
Section titled “Entry queries”| Code | HTTP | Meaning |
|---|---|---|
entry_query_invalid |
400 | The query string cannot be parsed, or a public key filtered on has_draft. |
entry_query_filters_invalid |
400 | The filters JSON is invalid. |
entry_query_limit_invalid |
400 | limit is not a positive integer. |
entry_query_limit_exceeded |
400 | limit is above the maximum. vars.limit, vars.max. |
entry_query_offset_invalid |
400 | offset is not a non-negative integer. |
entry_query_count_invalid |
400 | count is not a boolean. |
entry_query_include_field_invalid |
400 | include names an unknown or private field. vars.field. |
entry_query_exclude_field_invalid |
400 | exclude names an unknown field. vars.field. |
entry_query_include_exclude_conflict |
400 | include and exclude cannot be used together. |
entry_query_hydrate_field_invalid |
400 | hydrate: names a field that is not a reference. vars.field. |
entry_query_hydrate_invalid |
400 | A hydrate: value is malformed. vars.field. |
entry_query_hydrate_prefix_required |
400 | hydrate: fields must start with data.. vars.field. |
entry_query_where_field_invalid |
400 | where: names an unknown or private field. vars.field. |
entry_query_where_operator_invalid |
400 | where: uses an unknown operator. vars.param. |
entry_query_where_or_not_supported |
400 | The same where: parameter was repeated; use $in or a filters tree instead. vars.param. |
entry_query_sort_field_invalid |
400 | sort: names a field that cannot be sorted on. vars.field. |
entry_query_sort_direction_invalid |
400 | A sort direction is not asc or desc. vars.field, vars.direction. |
entry_query_sort_duplicate |
400 | The same sort field appears twice. vars.param. |
GraphQL
Section titled “GraphQL”Codes specific to POST /api/v1/graphql. A refusal of the request itself uses the error envelope; a refused operation answers { "data": null, "errors": [ … ] } with the code in each error’s extensions.code; a refused root field is null beside its error with the Content API’s own codes. See GraphQL API.
| Code | HTTP | Meaning |
|---|---|---|
graphql_request_invalid |
400 | The body is not a GraphQL request: malformed JSON, no query, a body over 1 MiB, or a non-query operation over GET. |
graphql_query_too_large |
400 | Query text over 50 KB. vars.bytes, vars.max. |
graphql_query_invalid |
400 | The query does not parse or fails validation against the site’s schema. |
graphql_query_too_deep |
400 | Nesting deeper than 10 levels. vars.depth, vars.max. |
graphql_query_too_complex |
400 | More than 20 root fields (vars.root_fields, vars.max_root_fields) or a complexity over 10 000 (vars.complexity, vars.max). |
graphql_query_timeout |
200 | The operation did not finish within 10 seconds. |
graphql_execution_failed |
200 | The executor refused the operation: a variable of the wrong type, or several operations without operationName. |
References
Section titled “References”| Code | HTTP | Meaning |
|---|---|---|
reference_field_required |
422 | The request must name the referencing model and field. |
reference_field_not_found |
422 | The referencing model has no such reference field. vars.model_key, vars.field_key. |
reference_group_not_found |
404 | No referencing group matches the request. |
reference_link_ids_required |
422 | No entry ids were given to link or unlink. |
reference_link_too_many |
422 | Too many entries in one link request. vars.count, vars.max. |
reference_path_unlinkable |
422 | This reference field cannot be linked from the receiving side. |
reference_unpublished |
409 | The field accepts only published entries and the target is a draft. |
Content folders
Section titled “Content folders”| Code | HTTP | Meaning |
|---|---|---|
folder_not_found |
404 | No such folder. |
folder_name_required |
422 | A folder needs a name. |
folder_slug_required |
422 | A folder needs a slug. |
folder_slug_invalid_format |
422 | The folder slug has invalid characters. |
folder_slug_taken |
409 | A sibling folder already uses this slug. |
folder_site_key_required |
422 | site_key is required for folder routes. |
folder_model_not_in_site |
422 | The model is not assigned to this site. |
folder_parent_not_found |
422 | The parent folder does not exist. |
folder_parent_cycle |
422 | The move would put a folder inside itself. |
folder_delete_conflict |
409 | Deleting the folder would move a child folder next to a sibling with the same slug. Rename one first. |
Content models and forms
Section titled “Content models and forms”| Code | HTTP | Meaning |
|---|---|---|
model_id_invalid |
400 | The model id in the path is not a valid id. |
model_not_found |
404 | No such model (forms are not found under /models). |
form_not_found |
404 | No such form (content models are not found under /forms). |
model_form_use_forms_api |
422 | Forms are created and edited through /api/v1/forms, not /api/v1/models. |
model_key_required |
422 | key is required. |
model_key_invalid_format |
422 | key must be lowercase letters, digits, and underscores, starting with a letter. |
model_key_taken |
409 | Another model or form on the same site already uses this key. |
model_object_key_prefix_required |
422 | Object model keys must start with obj_. |
model_kind_invalid |
422 | kind is not collection, singleton, object, or form. |
model_name_singular_required |
422 | name_singular is required. |
model_name_plural_required |
422 | name_plural is required. |
model_name_singular_taken |
409 | Another model on the same site already uses this singular name. |
model_name_plural_taken |
409 | Another model on the same site already uses this plural name. |
model_site_key_required |
422 | site_key is required when creating a model. On a request that names a model by key, two sites use that key: pass ?site_key=. vars.models lists the keys on an instance-wide YAML export. |
model_site_not_found |
422 | site_key names no site. |
model_site_key_immutable |
422 | A model cannot move to another site. |
model_reference_cross_site |
422 | A reference or object field points at a model on another site. |
model_title_field_unknown |
422 | title_field names no field. vars.field. |
model_title_field_type_invalid |
422 | The title field must be a scalar type. vars.field, vars.type. |
model_preview_url_unknown_ref |
422 | The preview URL template references an unknown field. vars.ref. |
model_has_entries |
409 | The model still has entries. Delete with purge_content to remove them too. |
model_key_confirm_required |
422 | Deleting a model needs ?key_confirm=<model key>. |
model_key_confirm_mismatch |
422 | key_confirm does not match the model’s key. |
model_object_field_invalid |
422 | An object field references an object model that does not exist or is not an object. |
model_field_key_required |
422 | A field has no key. vars.index. |
model_field_key_invalid_format |
422 | A field key has invalid characters. vars.index. |
model_field_key_duplicate |
422 | Two fields share a key. vars.index, vars.key. |
model_field_key_immutable |
422 | An existing field’s key cannot change. vars.index, vars.key. |
model_field_name_required |
422 | A field has no name. vars.index. |
model_field_type_invalid |
422 | A field’s type is not a known field type. vars.index. |
model_field_type_immutable |
422 | An existing field’s type cannot change. vars.index, vars.type. |
model_field_not_found |
422 | An update refers to a field id the model does not have. vars.index, vars.field_id. |
model_field_sort_order_duplicate |
422 | Two fields share a sort_order. vars.index, vars.sort_order. |
model_field_schema_invalid |
422 | A field’s validation, settings, or ui block is invalid. vars.field, vars.index, vars.path, vars.message. |
model_field_visible_when_invalid |
422 | A field’s visibility condition does not parse. vars.message. |
model_field_visible_when_unknown_ref |
422 | A field’s visibility condition references an unknown field. |
model_field_computed_source_required |
422 | A computed field has no template. vars.index. |
model_field_computed_source_invalid |
422 | A computed field’s template is invalid. vars.message. |
model_field_computed_source_unknown_ref |
422 | A computed field’s template references an unknown field. vars.ref. |
model_field_object_requires_definition |
422 | An object field must name an object model. vars.index. |
model_field_object_settings_invalid |
422 | An object field’s settings are invalid. vars.index. |
model_field_object_type_not_allowed |
422 | This field type is not allowed inside an object. vars.index. |
model_field_list_item_type_required |
422 | A list field needs an item type. vars.index. |
model_field_list_item_type_invalid |
422 | A list field’s item type is not allowed. vars.index, vars.item_type. |
model_field_list_object_requires_fields |
422 | A list of objects needs at least one sub-field. vars.index. |
model_field_list_settings_invalid |
422 | A list field’s settings are invalid. vars.index. |
model_list_title_field_unknown |
422 | A list field’s title field names no sub-field. vars.index, vars.title_field. |
model_list_title_field_type_invalid |
422 | A list field’s title sub-field must be a scalar type. vars.index, vars.title_field, vars.type. |
model_list_subfield_key_required |
422 | A list sub-field has no key. vars.index, vars.sub_index. |
model_list_subfield_key_invalid_format |
422 | A list sub-field key has invalid characters. vars.index, vars.sub_index. |
model_list_subfield_key_duplicate |
422 | Two list sub-fields share a key. vars.index, vars.sub_index, vars.key. |
model_list_subfield_name_required |
422 | A list sub-field has no name. vars.index, vars.sub_index. |
model_list_subfield_type_invalid |
422 | A list sub-field’s type is not allowed. vars.index, vars.sub_index. |
model_list_subfield_nested_not_supported |
422 | Lists cannot contain nested lists or objects at this level. vars.index, vars.sub_index. |
model_list_subfield_computed_not_supported |
422 | List sub-fields cannot be computed. vars.index, vars.sub_index. |
model_subfield_key_required |
422 | An object sub-field has no key. vars.index, vars.sub_index. |
model_subfield_key_invalid_format |
422 | An object sub-field key has invalid characters. vars.index, vars.sub_index. |
model_subfield_key_duplicate |
422 | Two object sub-fields share a key. vars.index, vars.sub_index, vars.key. |
model_subfield_name_required |
422 | An object sub-field has no name. vars.index, vars.sub_index. |
model_subfield_type_invalid |
422 | An object sub-field’s type is not allowed. vars.index, vars.sub_index. |
model_subfield_sort_order_duplicate |
422 | Two object sub-fields share a sort_order. vars.index, vars.sub_index, vars.sort_order. |
model_subfield_nested_object_not_supported |
422 | Objects cannot nest objects at this level. vars.index, vars.sub_index. |
model_form_field_type_not_allowed |
422 | This field type is not allowed on a form. vars.index, vars.type. |
model_form_field_localized_not_allowed |
422 | Form fields cannot be localized. vars.index. |
model_form_always_published_not_allowed |
422 | Forms cannot be always published. |
model_form_change_notes_not_allowed |
422 | Forms cannot require change notes. |
model_form_name_plural_not_allowed |
422 | Forms have no plural name. |
model_form_preview_not_allowed |
422 | Forms have no preview. |
model_form_private_not_allowed |
422 | Forms cannot be private. |
model_form_title_field_not_allowed |
422 | Forms have no title field. |
relationship_key_duplicate |
422 | Two relationships share a key. vars.index, vars.key. |
relationship_key_invalid_format |
422 | A relationship key has invalid characters. vars.index. |
relationship_label_required |
422 | A relationship needs a label. vars.index. |
relationship_source_required |
422 | A relationship must name its source model and field. vars.index. |
relationship_source_not_found |
422 | A relationship’s source model or field does not exist. vars.index, vars.source_model_id. |
relationship_source_duplicate |
422 | Two relationships name the same source. vars.index, vars.source. |
notification_recipient_invalid |
422 | A form notification recipient is malformed. vars.index. |
notification_recipient_role_unknown |
422 | A notification recipient names a role that does not exist. vars.index. |
notification_recipient_user_unknown |
422 | A notification recipient names a user that does not exist. vars.index. |
Transformers and webhooks
Section titled “Transformers and webhooks”| Code | HTTP | Meaning |
|---|---|---|
transformer_name_required |
422 | A transformer needs a name. vars.index. |
transformer_source_required |
422 | A transformer needs source code. vars.index, vars.name. |
transformer_source_invalid |
422 | A transformer’s source does not parse or uses something not allowed. vars.index, vars.name, vars.message. |
transformer_duplicate |
422 | The same transformer appears twice. vars.index, vars.id. |
transformer_not_found |
422 | An update refers to a transformer id the model does not have. vars.index, vars.id. |
webhook_not_found |
404 | No such webhook. |
webhook_name_required |
422 | A webhook needs a name. vars.index. |
webhook_url_invalid |
422 | A webhook URL is not a valid absolute URL. vars.index. |
webhook_url_requires_https |
422 | A webhook URL must use https. vars.index. |
webhook_events_empty |
422 | A webhook must subscribe to at least one event. vars.index. |
webhook_event_unknown |
422 | A webhook names an unknown event. vars.index, vars.event. |
webhook_payload_mode_invalid |
422 | A webhook’s payload mode is not recognized. vars.index, vars.mode. |
webhook_field_unknown |
422 | A webhook payload selects an unknown field. vars.index, vars.field. |
webhook_header_name_invalid |
422 | A custom header name is invalid. vars.index, vars.name. |
webhook_header_reserved |
422 | A custom header overrides a header Plenary sets. vars.index, vars.name. |
webhook_query_name_invalid |
422 | A query parameter name is invalid. vars.index, vars.name. |
Model YAML import
Section titled “Model YAML import”| Code | HTTP | Meaning |
|---|---|---|
metadata_files_required |
422 | The import request contains no files. |
metadata_invalid |
422 | A YAML file is invalid. vars.path, vars.message. |
metadata_kind_invalid |
422 | only names an unknown kind. vars.message. |
metadata_import_failed |
500 | The import stopped part-way. Run it again to finish. vars.message. |
Forms and form entries
Section titled “Forms and form entries”| Code | HTTP | Meaning |
|---|---|---|
form_entry_body_too_large |
413 | The submission body is too large. |
form_entry_rate_limited |
429 | Too many submissions from this IP address. |
form_entry_status_invalid |
422 | status is not a valid triage status. vars.status. |
form_entry_ids_required |
422 | A bulk status or delete request has no entry ids. |
form_entry_bulk_not_found |
422 | Some entries in a bulk request do not exist. vars.ids. |
form_entry_query_selection_unsupported |
400 | include and exclude are not supported on form entries. |
| Code | HTTP | Meaning |
|---|---|---|
media_id_invalid |
400 | The media id in the path is not valid. |
media_not_found |
404 | No such media item, or a private item requested with a public key. On bulk routes, vars.media_ids lists the missing ids. |
media_variant_key_required |
400 | The variant route needs a variant key. |
media_variant_not_found |
404 | The media item has no such variant. |
upload_field_required |
400 | The multipart upload has no upload_file part. |
upload_too_large |
413 | The upload exceeds the size limit. |
upload_failed |
500 | The file could not be stored. |
storage_unavailable |
500 | No storage backend could be resolved for the upload. |
media_type_invalid |
422 | The type filter is not a known media type. |
media_sort_invalid |
422 | The sort value is not supported. |
media_limit_invalid |
422 | limit is invalid. |
media_page_invalid |
422 | page is invalid. |
media_path_prefix_invalid |
422 | path_prefix is not a valid folder path. |
media_ids_required |
422 | A bulk request has no media ids. |
media_visibility_required |
422 | visibility is required. |
media_visibility_invalid |
422 | visibility is not public or private. |
media_relocation_failed |
500 | Moving files between the public and private roots failed part-way. Repeat the call to finish. vars.media_ids, vars.changed. |
media_folder_not_found |
404 / 422 | No such media folder. |
media_folder_name_required |
422 | A media folder needs a name. |
media_folder_slug_required |
422 | A media folder needs a slug. |
media_folder_slug_invalid_format |
422 | The media folder slug has invalid characters. |
media_folder_slug_taken |
409 | A sibling media folder already uses this slug. |
media_folder_parent_not_found |
422 | The parent media folder does not exist. |
media_folder_parent_cycle |
422 | The move would put a folder inside itself. |
media_folder_delete_conflict |
409 | Deleting the media folder would move a child folder next to a sibling with the same slug. Rename one first. |
Revisions
Section titled “Revisions”| Code | HTTP | Meaning |
|---|---|---|
revision_not_found |
404 | No such revision, or one you may not read. |
revision_query_limit_invalid |
400 | limit is invalid. |
revision_query_limit_exceeded |
400 | limit is above the maximum. vars.limit, vars.max. |
revision_query_offset_invalid |
400 | offset is invalid. |
revision_query_from_invalid |
400 | from is not a valid timestamp. |
revision_query_to_invalid |
400 | to is not a valid timestamp. |
revision_query_action_invalid |
400 | action is not a known revision action. vars.action. |
revision_query_actor_type_invalid |
400 | actor_type is not a known actor type. vars.actor_type. |
revision_query_target_type_invalid |
400 | target_type is not a known target type. |
Page Builder
Section titled “Page Builder”| Code | HTTP | Meaning |
|---|---|---|
manifest_site_key_required |
422 | site_key is required. |
manifest_too_large |
413 | The component manifest is too large. |
manifest_components_required |
422 | The manifest has no components. |
manifest_components_invalid |
422 | A component definition is invalid. vars.name, vars.reason. |
Users and accounts
Section titled “Users and accounts”| Code | HTTP | Meaning |
|---|---|---|
user_id_invalid |
400 | The user id in the path is not valid. |
user_not_found |
404 | No such user. |
user_identity_not_found |
404 | The user has no linked identity for that provider key. |
user_required_fields |
422 | A required field (username, email, first_name, last_name) is missing. |
username_invalid_format |
422 | The username has invalid characters. |
user_site_role_invalid |
422 | A site_roles entry is missing its site_key or role_key. |
user_site_role_duplicate |
422 | A site appears more than once in site_roles. |
user_site_role_site_not_found |
422 | A site_roles entry names no site. |
user_site_role_role_not_found |
422 | A site_roles entry names a role that does not exist on that site. |
user_super_user_self |
403 | You cannot change your own super user flag. |
user_deactivate_self |
403 | You cannot deactivate your own account. |
user_last_super_user |
409 | The change would leave no active super user. |
user_username_taken |
409 | Another user has this username. |
user_email_taken |
409 | Another user has this email address. |
user_sms_phone_taken |
409 | Another user has this phone number. |
user_sms_phone_invalid |
422 | sms_phone is not in E.164 format (+15551234567). |
user_avatar_invalid |
422 | avatar is not an image in the Media Library. |
user_avatar_focal_invalid |
422 | avatar_focal is out of range. |
user_delete_self |
403 | You cannot delete your own account. |
user_email_confirm_required |
400 | Deleting a user needs ?email_confirm=<their email>. |
user_email_confirm_mismatch |
422 | email_confirm does not match the user’s email address. |
user_query_field_invalid |
400 | The user list query names an unknown field. vars.field. |
user_query_operator_invalid |
400 | Unknown operator. vars.param. |
user_query_value_invalid |
400 | A filter value has the wrong type. vars.field. |
user_query_where_duplicate |
400 | The same filter parameter was repeated. vars.param. |
user_query_sort_direction_invalid |
400 | Sort direction is not asc or desc. vars.field, vars.direction. |
user_query_sort_duplicate |
400 | The same sort field appears twice. vars.param. |
user_query_limit_invalid |
400 | limit is invalid. |
user_query_limit_exceeded |
400 | limit is above the maximum. vars.limit, vars.max. |
user_query_offset_invalid |
400 | offset is invalid. |
user_query_count_invalid |
400 | count is not a boolean. |
account_field_not_editable |
422 | The field is not yours to change on Account Settings. vars.field. |
account_field_required |
422 | The field is required and cannot be emptied. vars.field. |
account_field_invalid |
422 | The field was sent with the wrong JSON type. vars.field. |
preference_key_invalid |
400 | The preference key is not valid. |
preference_value_invalid |
422 | The request has no preference value. |
preference_value_too_large |
413 | The preference value is too large. |
preference_limit_reached |
422 | You have reached the maximum number of stored preferences. |
Roles and grants
Section titled “Roles and grants”| Code | HTTP | Meaning |
|---|---|---|
role_not_found |
404 | No such role on this site. |
role_required_fields |
422 | key and name are required. |
role_name_required |
422 | name is required. |
role_key_taken |
409 | Another role on this site already uses this key. |
role_system_protected |
403 | A site’s Admin role cannot be changed or deleted. |
role_in_use |
409 | The role is still assigned to users. vars.users is how many. |
role_grant_key_invalid_format |
422 | A grant key is not shaped like domain:resource:action. Wildcards are not allowed. |
role_grant_keys_invalid |
422 | A grant key is not in the capability catalog. |
role_grant_duplicate |
422 | Two grants have the same key and filters. |
role_scope_not_allowed |
422 | A grant sets a filter its capability does not accept, or a role’s grant names another site or another site’s model. |
role_scope_target_not_found |
422 | A grant’s site or model filter names something that does not exist. |
API keys
Section titled “API keys”| Code | HTTP | Meaning |
|---|---|---|
api_key_id_invalid |
400 | The key id in the path is not valid. |
api_key_not_found |
404 | No such API key. |
api_key_name_required |
422 | name is required. |
api_key_type_invalid |
422 | key_type is not public or private. |
api_key_expires_at_invalid |
422 | expires_at is not an RFC 3339 timestamp. |
api_key_revoked_at_invalid |
422 | revoked_at is not an RFC 3339 timestamp. |
api_key_sites_required |
422 | A public key needs a site_key. |
api_key_site_not_found |
422 | site_key names no site. |
api_key_grant_site_mismatch |
422 | A site-bound private key’s grant names another site. |
api_key_grants_not_allowed |
422 | A public key cannot hold grants. |
api_key_grant_not_allowed |
422 | API keys may hold content:* capabilities only. vars.capabilities lists the rejected ones. |
api_key_origin_invalid |
422 | An allowed origin is not scheme://host[:port]. vars.origin. |
api_key_rate_limit_invalid |
422 | rate_limit_per_minute is negative. |
api_key_value_taken |
409 | A generated key collided with an existing one. Retry. |
api_key_delete_self |
403 | A key cannot delete itself. |
| Code | HTTP | Meaning |
|---|---|---|
site_not_found |
404 | No such site. |
site_key_required |
422 | key is required. |
site_key_invalid_format |
422 | The site key must be lowercase letters, digits, and underscores, starting with a letter. |
site_key_taken |
409 | Another site already uses this key. |
site_name_required |
422 | name is required. |
site_default_locale_invalid |
422 | default_locale is not a valid locale code. |
site_default_locale_not_allowed |
422 | default_locale is not in locales. |
site_locales_required |
422 | A site needs at least one locale. |
site_locales_invalid |
422 | locales contains an invalid code. |
site_timezone_invalid |
422 | timezone is not an IANA timezone name. |
site_key_confirm_mismatch |
400 | Deleting a site needs ?confirm_key=<site key>, and it did not match. |
site_has_entries |
400 | The site still has entries. Delete with purge_content=true to remove them too. |
site_last_site |
400 | The last remaining site cannot be deleted. |
site_has_models |
400 | The site still owns content models or forms. Delete them first. |
getting_started_site_key_required |
422 | The Getting Started request needs site_key. |
Settings
Section titled “Settings”| Code | HTTP | Meaning |
|---|---|---|
email_provider_invalid |
422 | provider is not an email provider this instance offers. |
email_settings_invalid |
422 | The email settings cannot produce a working provider. vars.reason. |
email_sending_disabled |
422 | A test email was requested while email sending is off. |
sms_provider_invalid |
422 | provider is not an SMS provider this instance offers. |
sms_settings_invalid |
422 | The SMS settings cannot produce a working provider. vars.reason. |
sms_sending_disabled |
422 | A test message was requested while SMS sending is off. |
storage_backend_invalid |
422 | backend is not local or s3. |
storage_settings_invalid |
422 | The S3 settings cannot produce a working backend. vars.reason. |
test_recipient_required |
422 | The test request has no to. |
test_recipient_invalid |
422 | The test email address is not valid. |
test_phone_invalid |
422 | The test phone number is not E.164. |
test_send_failed |
502 | The provider refused the test message. vars.reason. |
delivery_channel_invalid |
422 | channel must be email or sms. |
sso_protocol_invalid |
422 | protocol is not oidc or saml. Checked while the connection is enabled. |
sso_provisioning_mode_invalid |
422 | provisioning.mode is not linked_only or jit. |
sso_default_site_role_invalid |
422 | A default site role is missing its site_key or role_key, or a site appears twice. |
sso_default_site_role_site_not_found |
422 | A default site role names a site that does not exist. |
sso_default_site_role_role_not_found |
422 | A default site role names a role that does not exist on that site. |
sso_email_domain_invalid |
422 | An allowed email domain is blank or contains @, /, or a space. |
sso_oidc_issuer_url_invalid |
422 | oidc.issuer_url is not an absolute https URL. |
sso_oidc_client_id_required |
422 | An enabled OIDC connection has no client_id. |
sso_oidc_client_secret_required |
422 | An enabled OIDC connection has no stored client secret. |
sso_saml_idp_metadata_required |
422 | An enabled SAML connection has neither idp_metadata_url nor idp_metadata_xml. |
sso_saml_idp_metadata_url_invalid |
422 | saml.idp_metadata_url is not an absolute https URL. |
sso_connection_invalid |
422 | The connection cannot be built: OIDC discovery or the SAML metadata failed. vars.reason. |
Metrics
Section titled “Metrics”| Code | HTTP | Meaning |
|---|---|---|
metrics_date_invalid |
400 | from or to is not a YYYY-MM-DD date. |
metrics_range_invalid |
400 | from is after to, or days is not a positive integer. |
metrics_range_too_large |
400 | The range exceeds the endpoint’s maximum. |
First-run setup
Section titled “First-run setup”| Code | HTTP | Meaning |
|---|---|---|
setup_token_required |
401 | The setup wizard request has no setup token. |
setup_token_invalid |
401 | The setup wizard token is wrong. |
invalid_setup_token |
403 | POST /api/v1/setup/bootstrap was sent without the correct X-Setup-Token header. |
already_bootstrapped |
409 | The instance already has users, so it cannot be bootstrapped. |
setup_admin_required |
422 | Setup needs the first administrator’s details. |
setup_server_required |
422 | Setup needs the server settings. |
server_public_url_required |
422 | public_url is required. |
admin_required_fields |
422 | The administrator’s required fields are missing. |
invalid_email |
422 | The email address is not valid. |
password_and_hash_are_alternatives |
422 | Send a password or a password hash, not both. |
password_hash_not_bcrypt |
422 | The password hash is not a bcrypt hash. |
unknown_settings_group |
422 | The bootstrap names an unknown settings group. |
invalid_settings_group_body |
400 | A settings group’s body is invalid. |
setup_complete_failed |
500 | Setup could not be completed. See the server log. |
Related
Section titled “Related”- Permissions: what
permission_deniedis checking. - Authentication: sign-in and token errors in context.
- Licensing: license reasons and how to fix them.