Skip to content

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": {
"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.

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.

@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.

app/blog/[slug]/page.tsx
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.

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: 1

Some codes appear with two statuses: the one that applies depends on the route.

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.
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.
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.

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.
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).
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.
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.
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.

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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.