Copy an app into a new private app owned by the caller
Creates the caller a private copy of an app they can edit, or of a Template they may copy, without sending its source. A Template copy records the source as its origin (copyKind: "template"). The copy keeps the source code, styles, icon, and network settings; it never carries sharing, Public, signed-in access, Template or Listed state, tokens, secrets, Routines, Webhooks, custom domains, or version history. Without manifest_id the copy takes the next free manifest id after the source’s (<id>-2, <id>-3); a manifest_id the caller already holds is refused with 409 rather than replacing that app. include_data: true also copies the stored data and assets in the same transaction that creates the copy, so a copy exists with all of its data or not at all; it needs owner access to a personally owned source (a team app’s data is not copied into a personal account), and the data must fit the 24 MiB a copy carries, the per-app caps, and the caller’s storage allowance. Without idempotency_key every call creates a new copy and answers 200 with it; a retry with the same key answers with the copy, or the pending build, the first call made, and the same key with a different source, include_data, or manifest_id answers 409 idempotency_conflict. A 409 manifest_id_conflict names the app holding the id in existingAppId when one does. A package App copies through a build; a build that does not publish at once answers 202 with its build status, and the data copies when it publishes. secretsNotCopied names the source secrets to set on the copy; it is reported only to callers who can manage the source’s secrets.
/app/{id}/copyAuthorizationBearer token (chrm_user_*) · headerrequiredUser-scoped personal access token. Mint via POST /api/token after signing in, or via the device-pairing flow at POST /api/pair/start. Accepted by every operation that lists userToken in its security; operations that list only sessionCookie refuse it with 401 unauthorized.
idstringrequiredapplication/jsonmanifest_idstringManifest id for the copy. Must be free for the caller. Omit it to take the next free id.
display_namestringDisplay name for the copy. Defaults to the source's. Refused for package Apps, which name themselves in package.json.
idempotency_keystringNames this copy so a retry returns it instead of making another. The same key with a different source, include_data, or manifest_id answers 409 idempotency_conflict.
include_databooleanAlso copy the stored data and assets. Defaults to false. Needs owner access to a personally owned source; a team app’s data is not copied.
The copy.
okbooleanrequiredtrueidstring<uuid>requiredurlstring<uri>requiredmanifestIdstringrequiredappNamestring | nullrequireddisplayNamestringrequiredrevisionintegerrequiredsourceAppIdstring<uuid>requiredcopyKindstringrequiredapptemplatecopiedDataobjectPresent when include_data copied the data on this call. Absent on an idempotency replay, which returns the earlier copy without recounting.
Show propertiesHide properties
keysintegerrequiredassetsintegerrequiredsecretsNotCopiedstring[]Names of source secrets the copy does not have.
Package source accepted for a background build. This response does not mean the app has published. Poll statusUrl until a terminal state; new creation has no runnable app or URL until published.
okbooleanrequiredtruebuildIdstringrequiredintentstringrequiredcreateupdatemigraterestorecopystatestringrequiredqueuedresolvingbuildingvalidatingpublishedfailedsupersededcanceledexpiredsourceEtagstringrequiredThe ETag of the revision this build saved once an App exists, usable as If-Match on the next save. It doesn't change after a later save; GET /app/{id}/source returns the current one. Before a creation publishes, the digest of the accepted input.
statusUrlstring<uri>requiredretryAfterSecondsintegerappIdstring<uuid>revisionintegerPublished app source revision. Present only after successful publication.
desiredRevisionintegeractiveRevisionintegerurlstring<uri>attemptsintegerrequiredacceptedAtstring<date-time>requiredupdatedAtstring<date-time>requiredfinishedAtstring<date-time> | nullrequiredelapsedMsintegerrequiredlockStatestringrequiredlockedunresolvedinputDigeststringrequiredlockDigeststringresolvedDependenciesobjectExact versions of the top-level npm packages the retained lock installs, by package name. Absent while the build is unresolved and for builds whose lock predates the package resolution.
queueDeadlinestring<date-time>requireddeadlinestring<date-time>requiredinspectionExpiresAtstring<date-time> | nullrequiredidempotencyExpiresAtstring<date-time> | nullrequiredsourceobjectThe exact accepted package tree, when include_source=true and the inspection window is open.
Show propertiesHide properties
filesobjectrequirederrorobjectShow propertiesHide properties
kindstringrequiredmessagestringrequiredretryablebooleanrequireddetailsobjectShow propertiesHide properties
executionstringrequirednot_startedmay_have_runoperationIdstringrequiredreservationIdstringexecutionstringrequiredmay_have_runstagestringA stage only when the author's package caused the failure. source: the package was refused (its files, imports, or package.json, a size cap, a refused connect-src origin, a package name another App holds or that differs from the App's, or accepted source the current contract refuses); fix what the message names, in the file path names when given. dependencies: npm could not resolve or install the declared dependencies, or the tree has more packages than the limit; fix the package specifier names when given, its range in package.json, or trim the dependencies. compile: the compiler, or the check of the built server module, refused the App's code; fix the file and position named when given. Every other failure has no stage, because nothing in the package would fix it: a build sandbox, provider, executor, or database failing, a busy host, a cancellation, lost authority, an expired build or one that used up its attempts, an input Charming could not load, or a copy whose requested manifest id was taken. Save again.
sourcedependenciescompiletargetstringspecifierstringpathstringThe App file the failure points at, relative to the package root, when it points at one of the App's own files.
lineintegerThe 1-based line in path.
columnintegerThe 1-based column in line.
Body is not a JSON object, carries an unexpected key, or names an invalid manifest_id or display_name. See error.kind.
okbooleanrequiredfalseerrorobjectrequiredShow propertiesHide properties
kindstringrequiredStable enum-shaped error key. Branch on this for recovery flows.
not_foundunknown_operationoperation_not_foundmethod_not_allowedoperation_failedtimeoutapp_busyvisitor_rate_limitedservice_busyunauthorizedsign_in_requiredtoken_expiredforbiddenaccount_not_joinedstaff_onlytwo_factor_requiredreauthentication_requiredforbidden_writeview_as_read_onlyemail_not_verifiedemail_needs_sign_instored_value_too_largestorage_fulltoo_many_keysstorage_method_unavailableinvalid_moduleinvalid_uiinvalid_filesbearer_requiredunpinned_cdn_scriptinvalid_route_schemainvalid_routes_shapecontract_migration_requiredinvalid_manifest_schemainvalid_manifest_exportsinvalid_requestinvalid_inputinvalid_outputunexpected_keyscapability_deniedcapability_errorexecutor_errorinvalid_call_shapealready_claimedmanifest_not_foundpayload_too_largemodule_too_largeui_too_largestyles_too_largedescription_too_longmissing_descriptioninvalid_descriptionrate_limitedimage_origin_deniedtoo_many_requestsexpiredalready_approvedanon_not_remixabletemplate_listing_incompletetemplate_media_invalidtemplate_listing_too_largeforbidden_template_editinvalid_if_matchprecondition_requiredexpected_revision_requiredidempotency_key_requiredidempotency_conflictapp_build_capacityapp_build_failedapp_build_expiredapp_build_authority_lostapp_build_unavailableapp_build_unsupportedversion_history_unavailableversion_not_restorablerevision_mismatchinvalid_revisioncandidate_effects_unsupportedold_string_not_foundold_string_not_uniqueinvalid_bucketbucket_unsetempty_editsedits_too_largemanifest_id_conflictmanifest_id_immutabletext_too_largestructured_data_too_largeapp_not_foundfeedback_not_foundfeedback_has_no_reply_recipientasset_too_largeasset_count_exceededasset_quota_exceededasset_invalid_keyasset_invalid_content_typeasset_errorinvalid_idsse_cookie_expiredinvalid_secret_namesecret_too_largesecret_already_existssecret_not_foundinvalid_iconteam_slug_takenalready_membertwo_factor_requiredrecent_login_requiredgrantee_not_foundinvite_cap_reachedinvite_sender_blockedrole_above_owninvite_delegation_owner_onlynot_your_inviteread_onlyhandle_takeninvalid_handlename_takeninvalid_domaindomain_takendomain_existsdomain_provider_unavailableapp_unclaimedlink_cap_reachedgrantee_is_ownergrantee_is_selfgrantee_already_has_accessalready_invitedroutine_limit_exceededinvalid_intervalop_requires_inputduplicate_routinewebhook_limit_exceededduplicate_webhookwebhook_disabledversion_limit_exceededplan_requiredconnector_call_limit_exceededconnector_rate_limitedconnector_not_grantedconnector_action_not_declaredconnector_no_personconnector_reconnect_requiredconnector_unavailableconnector_tool_failedconnector_cross_siteconnector_blocked_by_teamconnector_route_not_declaredconnector_function_not_approvedconnector_version_retiredconnector_holder_onlystorage_limit_exceededcopy_data_forbiddencopy_data_too_largemessagestringreasonstringSet on 401s to distinguish token failure modes when finer detail is needed. token_revoked_post_claim is the post-#1284 surface for a chrm_app_* that was invalidated by a claim — the recovery field on the same error object carries the self-contained pairing-recovery hint the agent should follow instead of creating a new app.
token_malformedtoken_unknowntoken_revokedtoken_revoked_post_claimplanstringPresent on every plan refusal: the tier the caller was refused under. Its presence is what marks an error as a plan refusal rather than a validation or permission failure.
freeprobusinessenterpriselimitstring | integerWhich ceiling the call met, keyed by kind. A plan refusal (*_limit_exceeded) names the countable that ran out — version_history, routines_per_app, routines_per_owner, webhooks_per_app, webhooks_per_owner, connector_calls_per_month — and pairs it with max. An app_busy refusal names the bound it met and pairs it with observed and allowed; no plan lifts any of them. Two are per-app run bounds, concurrent_runs and runs_per_window; the third, render_token_refresh, is the page render asking for a new render-token secret, held by 10 per app per client IP and 60 per app across every address in a 60 second window, and observed/allowed name whichever of those two refused. An edits_too_large rejection carries the numeric cap that was exceeded instead of a name.
rungstringOn an app_busy refusal, how hard the app's own refusal ladder is refusing: throttled is the plain ceiling breach above; parked means a caller kept calling inside a wait it was given, so the server mints its own Retry-After (doubling from 60s to a 300s cap) and refuses until a quiet window passes even once the ceiling clears; closed is the same, plus the response closes the connection. Absent on every other kind.
throttledparkedclosedmaxintegerOn a *_limit_exceeded refusal, that limit's number on the caller's plan.
featurestringOn a plan_required refusal, the capability the plan does not include. Never paired with limit / max.
custom_domainwatermark_removalteamsupgradeUrlstring<uri>Absolute link to the owner's own billing page, where the refusal is lifted — the team's page for a team-owned app. Omitted only when the owner has no handle and therefore no settings page of their own, so treat it as optional and fall back to your own copy. MCP appends it as an Upgrade: <url> last line; the CLI prints it under the message.
missingLevelsstring[]On a connector_not_granted refusal, the access levels (in the order read, write, delete) the App's declared tools for the service need and the caller has not approved. Present only when approving would add something: call charming.connect(service) then. Absent means approving again would not help. On a refused PATCH /api/v1/apps/{appId}/connectors/{service}, the shared levels the holder's approval lacks instead.
recoveryRecoveryPair | RecoveryRetry | RecoveryShrink | RecoveryRefetch | RecoveryFixRouteLabel | RecoveryRename | RecoveryMigrateContractSelf-contained recovery hint, branching on kind. Attached to error envelopes the agent can self-correct on: pair for token_revoked_post_claim 401s (#1284), retry for 429s, shrink for too-large / quota-exceeded 413s, refetch for 412 revision_mismatch / invalid_if_match / 428 precondition_required, fix_route_label for 403 forbidden_write, rename for 409 manifest_id_immutable / manifest_id_conflict, and migrate_contract for 422 contract_migration_required. Every instructions string is a single-paragraph, action-first walk-through. Inlined per ADR 2026-05-06-agent-facing-error-surfaces-self-contain-the-fix.
Show propertiesHide properties
kindstringrequiredpairstartstring<uri>requiredverification_urlstring<uri>requiredinstructionsstringrequiredkindstringrequiredretryretry_after_secintegerrequiredSeconds to wait before retrying. Matches the RateLimit-Reset and Retry-After headers on the same response.
retry_after_urlstring<uri>requiredAbsolute URL to retry verbatim once the wait elapses.
instructionsstringrequiredkindstringrequiredshrinkfieldstringrequiredWhich input tripped the cap.
moduleuistylesdescriptiontextstructured_dataasseteditssecretpayloadsize_bytesintegerrequiredcap_bytesintegerrequiredinstructionsstringrequiredkindstringrequiredrefetchrefetch_urlstring<uri>requiredAbsolute URL to GET for the fresh ETag before retrying with a corrected If-Match.
instructionsstringrequiredkindstringrequiredfix_route_labelinstructionsstringrequiredApp-code recovery: the fix is in the route declaration, NOT in the request. Retrying the same request will fail again.
kindstringrequiredrenameinstructionsstringrequiredkindstringrequiredmigrate_contractinstructionsstringrequiredUser-scoped auth required.
okbooleanrequiredfalseerrorobjectrequiredShow propertiesHide properties
kindstringrequiredStable enum-shaped error key. Branch on this for recovery flows.
not_foundunknown_operationoperation_not_foundmethod_not_allowedoperation_failedtimeoutapp_busyvisitor_rate_limitedservice_busyunauthorizedsign_in_requiredtoken_expiredforbiddenaccount_not_joinedstaff_onlytwo_factor_requiredreauthentication_requiredforbidden_writeview_as_read_onlyemail_not_verifiedemail_needs_sign_instored_value_too_largestorage_fulltoo_many_keysstorage_method_unavailableinvalid_moduleinvalid_uiinvalid_filesbearer_requiredunpinned_cdn_scriptinvalid_route_schemainvalid_routes_shapecontract_migration_requiredinvalid_manifest_schemainvalid_manifest_exportsinvalid_requestinvalid_inputinvalid_outputunexpected_keyscapability_deniedcapability_errorexecutor_errorinvalid_call_shapealready_claimedmanifest_not_foundpayload_too_largemodule_too_largeui_too_largestyles_too_largedescription_too_longmissing_descriptioninvalid_descriptionrate_limitedimage_origin_deniedtoo_many_requestsexpiredalready_approvedanon_not_remixabletemplate_listing_incompletetemplate_media_invalidtemplate_listing_too_largeforbidden_template_editinvalid_if_matchprecondition_requiredexpected_revision_requiredidempotency_key_requiredidempotency_conflictapp_build_capacityapp_build_failedapp_build_expiredapp_build_authority_lostapp_build_unavailableapp_build_unsupportedversion_history_unavailableversion_not_restorablerevision_mismatchinvalid_revisioncandidate_effects_unsupportedold_string_not_foundold_string_not_uniqueinvalid_bucketbucket_unsetempty_editsedits_too_largemanifest_id_conflictmanifest_id_immutabletext_too_largestructured_data_too_largeapp_not_foundfeedback_not_foundfeedback_has_no_reply_recipientasset_too_largeasset_count_exceededasset_quota_exceededasset_invalid_keyasset_invalid_content_typeasset_errorinvalid_idsse_cookie_expiredinvalid_secret_namesecret_too_largesecret_already_existssecret_not_foundinvalid_iconteam_slug_takenalready_membertwo_factor_requiredrecent_login_requiredgrantee_not_foundinvite_cap_reachedinvite_sender_blockedrole_above_owninvite_delegation_owner_onlynot_your_inviteread_onlyhandle_takeninvalid_handlename_takeninvalid_domaindomain_takendomain_existsdomain_provider_unavailableapp_unclaimedlink_cap_reachedgrantee_is_ownergrantee_is_selfgrantee_already_has_accessalready_invitedroutine_limit_exceededinvalid_intervalop_requires_inputduplicate_routinewebhook_limit_exceededduplicate_webhookwebhook_disabledversion_limit_exceededplan_requiredconnector_call_limit_exceededconnector_rate_limitedconnector_not_grantedconnector_action_not_declaredconnector_no_personconnector_reconnect_requiredconnector_unavailableconnector_tool_failedconnector_cross_siteconnector_blocked_by_teamconnector_route_not_declaredconnector_function_not_approvedconnector_version_retiredconnector_holder_onlystorage_limit_exceededcopy_data_forbiddencopy_data_too_largemessagestringreasonstringSet on 401s to distinguish token failure modes when finer detail is needed. token_revoked_post_claim is the post-#1284 surface for a chrm_app_* that was invalidated by a claim — the recovery field on the same error object carries the self-contained pairing-recovery hint the agent should follow instead of creating a new app.
token_malformedtoken_unknowntoken_revokedtoken_revoked_post_claimplanstringPresent on every plan refusal: the tier the caller was refused under. Its presence is what marks an error as a plan refusal rather than a validation or permission failure.
freeprobusinessenterpriselimitstring | integerWhich ceiling the call met, keyed by kind. A plan refusal (*_limit_exceeded) names the countable that ran out — version_history, routines_per_app, routines_per_owner, webhooks_per_app, webhooks_per_owner, connector_calls_per_month — and pairs it with max. An app_busy refusal names the bound it met and pairs it with observed and allowed; no plan lifts any of them. Two are per-app run bounds, concurrent_runs and runs_per_window; the third, render_token_refresh, is the page render asking for a new render-token secret, held by 10 per app per client IP and 60 per app across every address in a 60 second window, and observed/allowed name whichever of those two refused. An edits_too_large rejection carries the numeric cap that was exceeded instead of a name.
rungstringOn an app_busy refusal, how hard the app's own refusal ladder is refusing: throttled is the plain ceiling breach above; parked means a caller kept calling inside a wait it was given, so the server mints its own Retry-After (doubling from 60s to a 300s cap) and refuses until a quiet window passes even once the ceiling clears; closed is the same, plus the response closes the connection. Absent on every other kind.
throttledparkedclosedmaxintegerOn a *_limit_exceeded refusal, that limit's number on the caller's plan.
featurestringOn a plan_required refusal, the capability the plan does not include. Never paired with limit / max.
custom_domainwatermark_removalteamsupgradeUrlstring<uri>Absolute link to the owner's own billing page, where the refusal is lifted — the team's page for a team-owned app. Omitted only when the owner has no handle and therefore no settings page of their own, so treat it as optional and fall back to your own copy. MCP appends it as an Upgrade: <url> last line; the CLI prints it under the message.
missingLevelsstring[]On a connector_not_granted refusal, the access levels (in the order read, write, delete) the App's declared tools for the service need and the caller has not approved. Present only when approving would add something: call charming.connect(service) then. Absent means approving again would not help. On a refused PATCH /api/v1/apps/{appId}/connectors/{service}, the shared levels the holder's approval lacks instead.
recoveryRecoveryPair | RecoveryRetry | RecoveryShrink | RecoveryRefetch | RecoveryFixRouteLabel | RecoveryRename | RecoveryMigrateContractSelf-contained recovery hint, branching on kind. Attached to error envelopes the agent can self-correct on: pair for token_revoked_post_claim 401s (#1284), retry for 429s, shrink for too-large / quota-exceeded 413s, refetch for 412 revision_mismatch / invalid_if_match / 428 precondition_required, fix_route_label for 403 forbidden_write, rename for 409 manifest_id_immutable / manifest_id_conflict, and migrate_contract for 422 contract_migration_required. Every instructions string is a single-paragraph, action-first walk-through. Inlined per ADR 2026-05-06-agent-facing-error-surfaces-self-contain-the-fix.
Show propertiesHide properties
kindstringrequiredpairstartstring<uri>requiredverification_urlstring<uri>requiredinstructionsstringrequiredkindstringrequiredretryretry_after_secintegerrequiredSeconds to wait before retrying. Matches the RateLimit-Reset and Retry-After headers on the same response.
retry_after_urlstring<uri>requiredAbsolute URL to retry verbatim once the wait elapses.
instructionsstringrequiredkindstringrequiredshrinkfieldstringrequiredWhich input tripped the cap.
moduleuistylesdescriptiontextstructured_dataasseteditssecretpayloadsize_bytesintegerrequiredcap_bytesintegerrequiredinstructionsstringrequiredkindstringrequiredrefetchrefetch_urlstring<uri>requiredAbsolute URL to GET for the fresh ETag before retrying with a corrected If-Match.
instructionsstringrequiredkindstringrequiredfix_route_labelinstructionsstringrequiredApp-code recovery: the fix is in the route declaration, NOT in the request. Retrying the same request will fail again.
kindstringrequiredrenameinstructionsstringrequiredkindstringrequiredmigrate_contractinstructionsstringrequiredforbidden: the caller can open the app but may not copy it. copy_data_forbidden: include_data needs owner access to a personally owned source, and a team app’s data is not copied.
okbooleanrequiredfalseerrorobjectrequiredShow propertiesHide properties
kindstringrequiredStable enum-shaped error key. Branch on this for recovery flows.
not_foundunknown_operationoperation_not_foundmethod_not_allowedoperation_failedtimeoutapp_busyvisitor_rate_limitedservice_busyunauthorizedsign_in_requiredtoken_expiredforbiddenaccount_not_joinedstaff_onlytwo_factor_requiredreauthentication_requiredforbidden_writeview_as_read_onlyemail_not_verifiedemail_needs_sign_instored_value_too_largestorage_fulltoo_many_keysstorage_method_unavailableinvalid_moduleinvalid_uiinvalid_filesbearer_requiredunpinned_cdn_scriptinvalid_route_schemainvalid_routes_shapecontract_migration_requiredinvalid_manifest_schemainvalid_manifest_exportsinvalid_requestinvalid_inputinvalid_outputunexpected_keyscapability_deniedcapability_errorexecutor_errorinvalid_call_shapealready_claimedmanifest_not_foundpayload_too_largemodule_too_largeui_too_largestyles_too_largedescription_too_longmissing_descriptioninvalid_descriptionrate_limitedimage_origin_deniedtoo_many_requestsexpiredalready_approvedanon_not_remixabletemplate_listing_incompletetemplate_media_invalidtemplate_listing_too_largeforbidden_template_editinvalid_if_matchprecondition_requiredexpected_revision_requiredidempotency_key_requiredidempotency_conflictapp_build_capacityapp_build_failedapp_build_expiredapp_build_authority_lostapp_build_unavailableapp_build_unsupportedversion_history_unavailableversion_not_restorablerevision_mismatchinvalid_revisioncandidate_effects_unsupportedold_string_not_foundold_string_not_uniqueinvalid_bucketbucket_unsetempty_editsedits_too_largemanifest_id_conflictmanifest_id_immutabletext_too_largestructured_data_too_largeapp_not_foundfeedback_not_foundfeedback_has_no_reply_recipientasset_too_largeasset_count_exceededasset_quota_exceededasset_invalid_keyasset_invalid_content_typeasset_errorinvalid_idsse_cookie_expiredinvalid_secret_namesecret_too_largesecret_already_existssecret_not_foundinvalid_iconteam_slug_takenalready_membertwo_factor_requiredrecent_login_requiredgrantee_not_foundinvite_cap_reachedinvite_sender_blockedrole_above_owninvite_delegation_owner_onlynot_your_inviteread_onlyhandle_takeninvalid_handlename_takeninvalid_domaindomain_takendomain_existsdomain_provider_unavailableapp_unclaimedlink_cap_reachedgrantee_is_ownergrantee_is_selfgrantee_already_has_accessalready_invitedroutine_limit_exceededinvalid_intervalop_requires_inputduplicate_routinewebhook_limit_exceededduplicate_webhookwebhook_disabledversion_limit_exceededplan_requiredconnector_call_limit_exceededconnector_rate_limitedconnector_not_grantedconnector_action_not_declaredconnector_no_personconnector_reconnect_requiredconnector_unavailableconnector_tool_failedconnector_cross_siteconnector_blocked_by_teamconnector_route_not_declaredconnector_function_not_approvedconnector_version_retiredconnector_holder_onlystorage_limit_exceededcopy_data_forbiddencopy_data_too_largemessagestringreasonstringSet on 401s to distinguish token failure modes when finer detail is needed. token_revoked_post_claim is the post-#1284 surface for a chrm_app_* that was invalidated by a claim — the recovery field on the same error object carries the self-contained pairing-recovery hint the agent should follow instead of creating a new app.
token_malformedtoken_unknowntoken_revokedtoken_revoked_post_claimplanstringPresent on every plan refusal: the tier the caller was refused under. Its presence is what marks an error as a plan refusal rather than a validation or permission failure.
freeprobusinessenterpriselimitstring | integerWhich ceiling the call met, keyed by kind. A plan refusal (*_limit_exceeded) names the countable that ran out — version_history, routines_per_app, routines_per_owner, webhooks_per_app, webhooks_per_owner, connector_calls_per_month — and pairs it with max. An app_busy refusal names the bound it met and pairs it with observed and allowed; no plan lifts any of them. Two are per-app run bounds, concurrent_runs and runs_per_window; the third, render_token_refresh, is the page render asking for a new render-token secret, held by 10 per app per client IP and 60 per app across every address in a 60 second window, and observed/allowed name whichever of those two refused. An edits_too_large rejection carries the numeric cap that was exceeded instead of a name.
rungstringOn an app_busy refusal, how hard the app's own refusal ladder is refusing: throttled is the plain ceiling breach above; parked means a caller kept calling inside a wait it was given, so the server mints its own Retry-After (doubling from 60s to a 300s cap) and refuses until a quiet window passes even once the ceiling clears; closed is the same, plus the response closes the connection. Absent on every other kind.
throttledparkedclosedmaxintegerOn a *_limit_exceeded refusal, that limit's number on the caller's plan.
featurestringOn a plan_required refusal, the capability the plan does not include. Never paired with limit / max.
custom_domainwatermark_removalteamsupgradeUrlstring<uri>Absolute link to the owner's own billing page, where the refusal is lifted — the team's page for a team-owned app. Omitted only when the owner has no handle and therefore no settings page of their own, so treat it as optional and fall back to your own copy. MCP appends it as an Upgrade: <url> last line; the CLI prints it under the message.
missingLevelsstring[]On a connector_not_granted refusal, the access levels (in the order read, write, delete) the App's declared tools for the service need and the caller has not approved. Present only when approving would add something: call charming.connect(service) then. Absent means approving again would not help. On a refused PATCH /api/v1/apps/{appId}/connectors/{service}, the shared levels the holder's approval lacks instead.
recoveryRecoveryPair | RecoveryRetry | RecoveryShrink | RecoveryRefetch | RecoveryFixRouteLabel | RecoveryRename | RecoveryMigrateContractSelf-contained recovery hint, branching on kind. Attached to error envelopes the agent can self-correct on: pair for token_revoked_post_claim 401s (#1284), retry for 429s, shrink for too-large / quota-exceeded 413s, refetch for 412 revision_mismatch / invalid_if_match / 428 precondition_required, fix_route_label for 403 forbidden_write, rename for 409 manifest_id_immutable / manifest_id_conflict, and migrate_contract for 422 contract_migration_required. Every instructions string is a single-paragraph, action-first walk-through. Inlined per ADR 2026-05-06-agent-facing-error-surfaces-self-contain-the-fix.
Show propertiesHide properties
kindstringrequiredpairstartstring<uri>requiredverification_urlstring<uri>requiredinstructionsstringrequiredkindstringrequiredretryretry_after_secintegerrequiredSeconds to wait before retrying. Matches the RateLimit-Reset and Retry-After headers on the same response.
retry_after_urlstring<uri>requiredAbsolute URL to retry verbatim once the wait elapses.
instructionsstringrequiredkindstringrequiredshrinkfieldstringrequiredWhich input tripped the cap.
moduleuistylesdescriptiontextstructured_dataasseteditssecretpayloadsize_bytesintegerrequiredcap_bytesintegerrequiredinstructionsstringrequiredkindstringrequiredrefetchrefetch_urlstring<uri>requiredAbsolute URL to GET for the fresh ETag before retrying with a corrected If-Match.
instructionsstringrequiredkindstringrequiredfix_route_labelinstructionsstringrequiredApp-code recovery: the fix is in the route declaration, NOT in the request. Retrying the same request will fail again.
kindstringrequiredrenameinstructionsstringrequiredkindstringrequiredmigrate_contractinstructionsstringrequiredApp not found, or the caller cannot open it.
okbooleanrequiredfalseerrorobjectrequiredShow propertiesHide properties
kindstringrequiredStable enum-shaped error key. Branch on this for recovery flows.
not_foundunknown_operationoperation_not_foundmethod_not_allowedoperation_failedtimeoutapp_busyvisitor_rate_limitedservice_busyunauthorizedsign_in_requiredtoken_expiredforbiddenaccount_not_joinedstaff_onlytwo_factor_requiredreauthentication_requiredforbidden_writeview_as_read_onlyemail_not_verifiedemail_needs_sign_instored_value_too_largestorage_fulltoo_many_keysstorage_method_unavailableinvalid_moduleinvalid_uiinvalid_filesbearer_requiredunpinned_cdn_scriptinvalid_route_schemainvalid_routes_shapecontract_migration_requiredinvalid_manifest_schemainvalid_manifest_exportsinvalid_requestinvalid_inputinvalid_outputunexpected_keyscapability_deniedcapability_errorexecutor_errorinvalid_call_shapealready_claimedmanifest_not_foundpayload_too_largemodule_too_largeui_too_largestyles_too_largedescription_too_longmissing_descriptioninvalid_descriptionrate_limitedimage_origin_deniedtoo_many_requestsexpiredalready_approvedanon_not_remixabletemplate_listing_incompletetemplate_media_invalidtemplate_listing_too_largeforbidden_template_editinvalid_if_matchprecondition_requiredexpected_revision_requiredidempotency_key_requiredidempotency_conflictapp_build_capacityapp_build_failedapp_build_expiredapp_build_authority_lostapp_build_unavailableapp_build_unsupportedversion_history_unavailableversion_not_restorablerevision_mismatchinvalid_revisioncandidate_effects_unsupportedold_string_not_foundold_string_not_uniqueinvalid_bucketbucket_unsetempty_editsedits_too_largemanifest_id_conflictmanifest_id_immutabletext_too_largestructured_data_too_largeapp_not_foundfeedback_not_foundfeedback_has_no_reply_recipientasset_too_largeasset_count_exceededasset_quota_exceededasset_invalid_keyasset_invalid_content_typeasset_errorinvalid_idsse_cookie_expiredinvalid_secret_namesecret_too_largesecret_already_existssecret_not_foundinvalid_iconteam_slug_takenalready_membertwo_factor_requiredrecent_login_requiredgrantee_not_foundinvite_cap_reachedinvite_sender_blockedrole_above_owninvite_delegation_owner_onlynot_your_inviteread_onlyhandle_takeninvalid_handlename_takeninvalid_domaindomain_takendomain_existsdomain_provider_unavailableapp_unclaimedlink_cap_reachedgrantee_is_ownergrantee_is_selfgrantee_already_has_accessalready_invitedroutine_limit_exceededinvalid_intervalop_requires_inputduplicate_routinewebhook_limit_exceededduplicate_webhookwebhook_disabledversion_limit_exceededplan_requiredconnector_call_limit_exceededconnector_rate_limitedconnector_not_grantedconnector_action_not_declaredconnector_no_personconnector_reconnect_requiredconnector_unavailableconnector_tool_failedconnector_cross_siteconnector_blocked_by_teamconnector_route_not_declaredconnector_function_not_approvedconnector_version_retiredconnector_holder_onlystorage_limit_exceededcopy_data_forbiddencopy_data_too_largemessagestringreasonstringSet on 401s to distinguish token failure modes when finer detail is needed. token_revoked_post_claim is the post-#1284 surface for a chrm_app_* that was invalidated by a claim — the recovery field on the same error object carries the self-contained pairing-recovery hint the agent should follow instead of creating a new app.
token_malformedtoken_unknowntoken_revokedtoken_revoked_post_claimplanstringPresent on every plan refusal: the tier the caller was refused under. Its presence is what marks an error as a plan refusal rather than a validation or permission failure.
freeprobusinessenterpriselimitstring | integerWhich ceiling the call met, keyed by kind. A plan refusal (*_limit_exceeded) names the countable that ran out — version_history, routines_per_app, routines_per_owner, webhooks_per_app, webhooks_per_owner, connector_calls_per_month — and pairs it with max. An app_busy refusal names the bound it met and pairs it with observed and allowed; no plan lifts any of them. Two are per-app run bounds, concurrent_runs and runs_per_window; the third, render_token_refresh, is the page render asking for a new render-token secret, held by 10 per app per client IP and 60 per app across every address in a 60 second window, and observed/allowed name whichever of those two refused. An edits_too_large rejection carries the numeric cap that was exceeded instead of a name.
rungstringOn an app_busy refusal, how hard the app's own refusal ladder is refusing: throttled is the plain ceiling breach above; parked means a caller kept calling inside a wait it was given, so the server mints its own Retry-After (doubling from 60s to a 300s cap) and refuses until a quiet window passes even once the ceiling clears; closed is the same, plus the response closes the connection. Absent on every other kind.
throttledparkedclosedmaxintegerOn a *_limit_exceeded refusal, that limit's number on the caller's plan.
featurestringOn a plan_required refusal, the capability the plan does not include. Never paired with limit / max.
custom_domainwatermark_removalteamsupgradeUrlstring<uri>Absolute link to the owner's own billing page, where the refusal is lifted — the team's page for a team-owned app. Omitted only when the owner has no handle and therefore no settings page of their own, so treat it as optional and fall back to your own copy. MCP appends it as an Upgrade: <url> last line; the CLI prints it under the message.
missingLevelsstring[]On a connector_not_granted refusal, the access levels (in the order read, write, delete) the App's declared tools for the service need and the caller has not approved. Present only when approving would add something: call charming.connect(service) then. Absent means approving again would not help. On a refused PATCH /api/v1/apps/{appId}/connectors/{service}, the shared levels the holder's approval lacks instead.
recoveryRecoveryPair | RecoveryRetry | RecoveryShrink | RecoveryRefetch | RecoveryFixRouteLabel | RecoveryRename | RecoveryMigrateContractSelf-contained recovery hint, branching on kind. Attached to error envelopes the agent can self-correct on: pair for token_revoked_post_claim 401s (#1284), retry for 429s, shrink for too-large / quota-exceeded 413s, refetch for 412 revision_mismatch / invalid_if_match / 428 precondition_required, fix_route_label for 403 forbidden_write, rename for 409 manifest_id_immutable / manifest_id_conflict, and migrate_contract for 422 contract_migration_required. Every instructions string is a single-paragraph, action-first walk-through. Inlined per ADR 2026-05-06-agent-facing-error-surfaces-self-contain-the-fix.
Show propertiesHide properties
kindstringrequiredpairstartstring<uri>requiredverification_urlstring<uri>requiredinstructionsstringrequiredkindstringrequiredretryretry_after_secintegerrequiredSeconds to wait before retrying. Matches the RateLimit-Reset and Retry-After headers on the same response.
retry_after_urlstring<uri>requiredAbsolute URL to retry verbatim once the wait elapses.
instructionsstringrequiredkindstringrequiredshrinkfieldstringrequiredWhich input tripped the cap.
moduleuistylesdescriptiontextstructured_dataasseteditssecretpayloadsize_bytesintegerrequiredcap_bytesintegerrequiredinstructionsstringrequiredkindstringrequiredrefetchrefetch_urlstring<uri>requiredAbsolute URL to GET for the fresh ETag before retrying with a corrected If-Match.
instructionsstringrequiredkindstringrequiredfix_route_labelinstructionsstringrequiredApp-code recovery: the fix is in the route declaration, NOT in the request. Retrying the same request will fail again.
kindstringrequiredrenameinstructionsstringrequiredkindstringrequiredmigrate_contractinstructionsstringrequiredmanifest_id_conflict: the caller already holds the requested manifest_id; existingAppId names the app when one holds it. idempotency_conflict: the idempotency_key already copied a different app.
okbooleanrequiredfalseerrorobjectrequiredShow propertiesHide properties
kindstringrequiredStable enum-shaped error key. Branch on this for recovery flows.
not_foundunknown_operationoperation_not_foundmethod_not_allowedoperation_failedtimeoutapp_busyvisitor_rate_limitedservice_busyunauthorizedsign_in_requiredtoken_expiredforbiddenaccount_not_joinedstaff_onlytwo_factor_requiredreauthentication_requiredforbidden_writeview_as_read_onlyemail_not_verifiedemail_needs_sign_instored_value_too_largestorage_fulltoo_many_keysstorage_method_unavailableinvalid_moduleinvalid_uiinvalid_filesbearer_requiredunpinned_cdn_scriptinvalid_route_schemainvalid_routes_shapecontract_migration_requiredinvalid_manifest_schemainvalid_manifest_exportsinvalid_requestinvalid_inputinvalid_outputunexpected_keyscapability_deniedcapability_errorexecutor_errorinvalid_call_shapealready_claimedmanifest_not_foundpayload_too_largemodule_too_largeui_too_largestyles_too_largedescription_too_longmissing_descriptioninvalid_descriptionrate_limitedimage_origin_deniedtoo_many_requestsexpiredalready_approvedanon_not_remixabletemplate_listing_incompletetemplate_media_invalidtemplate_listing_too_largeforbidden_template_editinvalid_if_matchprecondition_requiredexpected_revision_requiredidempotency_key_requiredidempotency_conflictapp_build_capacityapp_build_failedapp_build_expiredapp_build_authority_lostapp_build_unavailableapp_build_unsupportedversion_history_unavailableversion_not_restorablerevision_mismatchinvalid_revisioncandidate_effects_unsupportedold_string_not_foundold_string_not_uniqueinvalid_bucketbucket_unsetempty_editsedits_too_largemanifest_id_conflictmanifest_id_immutabletext_too_largestructured_data_too_largeapp_not_foundfeedback_not_foundfeedback_has_no_reply_recipientasset_too_largeasset_count_exceededasset_quota_exceededasset_invalid_keyasset_invalid_content_typeasset_errorinvalid_idsse_cookie_expiredinvalid_secret_namesecret_too_largesecret_already_existssecret_not_foundinvalid_iconteam_slug_takenalready_membertwo_factor_requiredrecent_login_requiredgrantee_not_foundinvite_cap_reachedinvite_sender_blockedrole_above_owninvite_delegation_owner_onlynot_your_inviteread_onlyhandle_takeninvalid_handlename_takeninvalid_domaindomain_takendomain_existsdomain_provider_unavailableapp_unclaimedlink_cap_reachedgrantee_is_ownergrantee_is_selfgrantee_already_has_accessalready_invitedroutine_limit_exceededinvalid_intervalop_requires_inputduplicate_routinewebhook_limit_exceededduplicate_webhookwebhook_disabledversion_limit_exceededplan_requiredconnector_call_limit_exceededconnector_rate_limitedconnector_not_grantedconnector_action_not_declaredconnector_no_personconnector_reconnect_requiredconnector_unavailableconnector_tool_failedconnector_cross_siteconnector_blocked_by_teamconnector_route_not_declaredconnector_function_not_approvedconnector_version_retiredconnector_holder_onlystorage_limit_exceededcopy_data_forbiddencopy_data_too_largemessagestringreasonstringSet on 401s to distinguish token failure modes when finer detail is needed. token_revoked_post_claim is the post-#1284 surface for a chrm_app_* that was invalidated by a claim — the recovery field on the same error object carries the self-contained pairing-recovery hint the agent should follow instead of creating a new app.
token_malformedtoken_unknowntoken_revokedtoken_revoked_post_claimplanstringPresent on every plan refusal: the tier the caller was refused under. Its presence is what marks an error as a plan refusal rather than a validation or permission failure.
freeprobusinessenterpriselimitstring | integerWhich ceiling the call met, keyed by kind. A plan refusal (*_limit_exceeded) names the countable that ran out — version_history, routines_per_app, routines_per_owner, webhooks_per_app, webhooks_per_owner, connector_calls_per_month — and pairs it with max. An app_busy refusal names the bound it met and pairs it with observed and allowed; no plan lifts any of them. Two are per-app run bounds, concurrent_runs and runs_per_window; the third, render_token_refresh, is the page render asking for a new render-token secret, held by 10 per app per client IP and 60 per app across every address in a 60 second window, and observed/allowed name whichever of those two refused. An edits_too_large rejection carries the numeric cap that was exceeded instead of a name.
rungstringOn an app_busy refusal, how hard the app's own refusal ladder is refusing: throttled is the plain ceiling breach above; parked means a caller kept calling inside a wait it was given, so the server mints its own Retry-After (doubling from 60s to a 300s cap) and refuses until a quiet window passes even once the ceiling clears; closed is the same, plus the response closes the connection. Absent on every other kind.
throttledparkedclosedmaxintegerOn a *_limit_exceeded refusal, that limit's number on the caller's plan.
featurestringOn a plan_required refusal, the capability the plan does not include. Never paired with limit / max.
custom_domainwatermark_removalteamsupgradeUrlstring<uri>Absolute link to the owner's own billing page, where the refusal is lifted — the team's page for a team-owned app. Omitted only when the owner has no handle and therefore no settings page of their own, so treat it as optional and fall back to your own copy. MCP appends it as an Upgrade: <url> last line; the CLI prints it under the message.
missingLevelsstring[]On a connector_not_granted refusal, the access levels (in the order read, write, delete) the App's declared tools for the service need and the caller has not approved. Present only when approving would add something: call charming.connect(service) then. Absent means approving again would not help. On a refused PATCH /api/v1/apps/{appId}/connectors/{service}, the shared levels the holder's approval lacks instead.
recoveryRecoveryPair | RecoveryRetry | RecoveryShrink | RecoveryRefetch | RecoveryFixRouteLabel | RecoveryRename | RecoveryMigrateContractSelf-contained recovery hint, branching on kind. Attached to error envelopes the agent can self-correct on: pair for token_revoked_post_claim 401s (#1284), retry for 429s, shrink for too-large / quota-exceeded 413s, refetch for 412 revision_mismatch / invalid_if_match / 428 precondition_required, fix_route_label for 403 forbidden_write, rename for 409 manifest_id_immutable / manifest_id_conflict, and migrate_contract for 422 contract_migration_required. Every instructions string is a single-paragraph, action-first walk-through. Inlined per ADR 2026-05-06-agent-facing-error-surfaces-self-contain-the-fix.
Show propertiesHide properties
kindstringrequiredpairstartstring<uri>requiredverification_urlstring<uri>requiredinstructionsstringrequiredkindstringrequiredretryretry_after_secintegerrequiredSeconds to wait before retrying. Matches the RateLimit-Reset and Retry-After headers on the same response.
retry_after_urlstring<uri>requiredAbsolute URL to retry verbatim once the wait elapses.
instructionsstringrequiredkindstringrequiredshrinkfieldstringrequiredWhich input tripped the cap.
moduleuistylesdescriptiontextstructured_dataasseteditssecretpayloadsize_bytesintegerrequiredcap_bytesintegerrequiredinstructionsstringrequiredkindstringrequiredrefetchrefetch_urlstring<uri>requiredAbsolute URL to GET for the fresh ETag before retrying with a corrected If-Match.
instructionsstringrequiredkindstringrequiredfix_route_labelinstructionsstringrequiredApp-code recovery: the fix is in the route declaration, NOT in the request. Retrying the same request will fail again.
kindstringrequiredrenameinstructionsstringrequiredkindstringrequiredmigrate_contractinstructionsstringrequiredThe source data exceeds the 24 MiB a copy carries (copy_data_too_large) or a per-app cap (storage_full, asset_count_exceeded, asset_quota_exceeded). Copy it without include_data.
okbooleanrequiredfalseerrorobjectrequiredShow propertiesHide properties
kindstringrequiredStable enum-shaped error key. Branch on this for recovery flows.
not_foundunknown_operationoperation_not_foundmethod_not_allowedoperation_failedtimeoutapp_busyvisitor_rate_limitedservice_busyunauthorizedsign_in_requiredtoken_expiredforbiddenaccount_not_joinedstaff_onlytwo_factor_requiredreauthentication_requiredforbidden_writeview_as_read_onlyemail_not_verifiedemail_needs_sign_instored_value_too_largestorage_fulltoo_many_keysstorage_method_unavailableinvalid_moduleinvalid_uiinvalid_filesbearer_requiredunpinned_cdn_scriptinvalid_route_schemainvalid_routes_shapecontract_migration_requiredinvalid_manifest_schemainvalid_manifest_exportsinvalid_requestinvalid_inputinvalid_outputunexpected_keyscapability_deniedcapability_errorexecutor_errorinvalid_call_shapealready_claimedmanifest_not_foundpayload_too_largemodule_too_largeui_too_largestyles_too_largedescription_too_longmissing_descriptioninvalid_descriptionrate_limitedimage_origin_deniedtoo_many_requestsexpiredalready_approvedanon_not_remixabletemplate_listing_incompletetemplate_media_invalidtemplate_listing_too_largeforbidden_template_editinvalid_if_matchprecondition_requiredexpected_revision_requiredidempotency_key_requiredidempotency_conflictapp_build_capacityapp_build_failedapp_build_expiredapp_build_authority_lostapp_build_unavailableapp_build_unsupportedversion_history_unavailableversion_not_restorablerevision_mismatchinvalid_revisioncandidate_effects_unsupportedold_string_not_foundold_string_not_uniqueinvalid_bucketbucket_unsetempty_editsedits_too_largemanifest_id_conflictmanifest_id_immutabletext_too_largestructured_data_too_largeapp_not_foundfeedback_not_foundfeedback_has_no_reply_recipientasset_too_largeasset_count_exceededasset_quota_exceededasset_invalid_keyasset_invalid_content_typeasset_errorinvalid_idsse_cookie_expiredinvalid_secret_namesecret_too_largesecret_already_existssecret_not_foundinvalid_iconteam_slug_takenalready_membertwo_factor_requiredrecent_login_requiredgrantee_not_foundinvite_cap_reachedinvite_sender_blockedrole_above_owninvite_delegation_owner_onlynot_your_inviteread_onlyhandle_takeninvalid_handlename_takeninvalid_domaindomain_takendomain_existsdomain_provider_unavailableapp_unclaimedlink_cap_reachedgrantee_is_ownergrantee_is_selfgrantee_already_has_accessalready_invitedroutine_limit_exceededinvalid_intervalop_requires_inputduplicate_routinewebhook_limit_exceededduplicate_webhookwebhook_disabledversion_limit_exceededplan_requiredconnector_call_limit_exceededconnector_rate_limitedconnector_not_grantedconnector_action_not_declaredconnector_no_personconnector_reconnect_requiredconnector_unavailableconnector_tool_failedconnector_cross_siteconnector_blocked_by_teamconnector_route_not_declaredconnector_function_not_approvedconnector_version_retiredconnector_holder_onlystorage_limit_exceededcopy_data_forbiddencopy_data_too_largemessagestringreasonstringSet on 401s to distinguish token failure modes when finer detail is needed. token_revoked_post_claim is the post-#1284 surface for a chrm_app_* that was invalidated by a claim — the recovery field on the same error object carries the self-contained pairing-recovery hint the agent should follow instead of creating a new app.
token_malformedtoken_unknowntoken_revokedtoken_revoked_post_claimplanstringPresent on every plan refusal: the tier the caller was refused under. Its presence is what marks an error as a plan refusal rather than a validation or permission failure.
freeprobusinessenterpriselimitstring | integerWhich ceiling the call met, keyed by kind. A plan refusal (*_limit_exceeded) names the countable that ran out — version_history, routines_per_app, routines_per_owner, webhooks_per_app, webhooks_per_owner, connector_calls_per_month — and pairs it with max. An app_busy refusal names the bound it met and pairs it with observed and allowed; no plan lifts any of them. Two are per-app run bounds, concurrent_runs and runs_per_window; the third, render_token_refresh, is the page render asking for a new render-token secret, held by 10 per app per client IP and 60 per app across every address in a 60 second window, and observed/allowed name whichever of those two refused. An edits_too_large rejection carries the numeric cap that was exceeded instead of a name.
rungstringOn an app_busy refusal, how hard the app's own refusal ladder is refusing: throttled is the plain ceiling breach above; parked means a caller kept calling inside a wait it was given, so the server mints its own Retry-After (doubling from 60s to a 300s cap) and refuses until a quiet window passes even once the ceiling clears; closed is the same, plus the response closes the connection. Absent on every other kind.
throttledparkedclosedmaxintegerOn a *_limit_exceeded refusal, that limit's number on the caller's plan.
featurestringOn a plan_required refusal, the capability the plan does not include. Never paired with limit / max.
custom_domainwatermark_removalteamsupgradeUrlstring<uri>Absolute link to the owner's own billing page, where the refusal is lifted — the team's page for a team-owned app. Omitted only when the owner has no handle and therefore no settings page of their own, so treat it as optional and fall back to your own copy. MCP appends it as an Upgrade: <url> last line; the CLI prints it under the message.
missingLevelsstring[]On a connector_not_granted refusal, the access levels (in the order read, write, delete) the App's declared tools for the service need and the caller has not approved. Present only when approving would add something: call charming.connect(service) then. Absent means approving again would not help. On a refused PATCH /api/v1/apps/{appId}/connectors/{service}, the shared levels the holder's approval lacks instead.
recoveryRecoveryPair | RecoveryRetry | RecoveryShrink | RecoveryRefetch | RecoveryFixRouteLabel | RecoveryRename | RecoveryMigrateContractSelf-contained recovery hint, branching on kind. Attached to error envelopes the agent can self-correct on: pair for token_revoked_post_claim 401s (#1284), retry for 429s, shrink for too-large / quota-exceeded 413s, refetch for 412 revision_mismatch / invalid_if_match / 428 precondition_required, fix_route_label for 403 forbidden_write, rename for 409 manifest_id_immutable / manifest_id_conflict, and migrate_contract for 422 contract_migration_required. Every instructions string is a single-paragraph, action-first walk-through. Inlined per ADR 2026-05-06-agent-facing-error-surfaces-self-contain-the-fix.
Show propertiesHide properties
kindstringrequiredpairstartstring<uri>requiredverification_urlstring<uri>requiredinstructionsstringrequiredkindstringrequiredretryretry_after_secintegerrequiredSeconds to wait before retrying. Matches the RateLimit-Reset and Retry-After headers on the same response.
retry_after_urlstring<uri>requiredAbsolute URL to retry verbatim once the wait elapses.
instructionsstringrequiredkindstringrequiredshrinkfieldstringrequiredWhich input tripped the cap.
moduleuistylesdescriptiontextstructured_dataasseteditssecretpayloadsize_bytesintegerrequiredcap_bytesintegerrequiredinstructionsstringrequiredkindstringrequiredrefetchrefetch_urlstring<uri>requiredAbsolute URL to GET for the fresh ETag before retrying with a corrected If-Match.
instructionsstringrequiredkindstringrequiredfix_route_labelinstructionsstringrequiredApp-code recovery: the fix is in the route declaration, NOT in the request. Retrying the same request will fail again.
kindstringrequiredrenameinstructionsstringrequiredkindstringrequiredmigrate_contractinstructionsstringrequiredrate_limited: the account made more than 60 creates and copies in a minute; retry after the returned delay. storage_limit_exceeded: the data would put the caller over their storage allowance. app_build_capacity: retry after the returned delay.
okbooleanrequiredfalseerrorobjectrequiredShow propertiesHide properties
kindstringrequiredStable enum-shaped error key. Branch on this for recovery flows.
not_foundunknown_operationoperation_not_foundmethod_not_allowedoperation_failedtimeoutapp_busyvisitor_rate_limitedservice_busyunauthorizedsign_in_requiredtoken_expiredforbiddenaccount_not_joinedstaff_onlytwo_factor_requiredreauthentication_requiredforbidden_writeview_as_read_onlyemail_not_verifiedemail_needs_sign_instored_value_too_largestorage_fulltoo_many_keysstorage_method_unavailableinvalid_moduleinvalid_uiinvalid_filesbearer_requiredunpinned_cdn_scriptinvalid_route_schemainvalid_routes_shapecontract_migration_requiredinvalid_manifest_schemainvalid_manifest_exportsinvalid_requestinvalid_inputinvalid_outputunexpected_keyscapability_deniedcapability_errorexecutor_errorinvalid_call_shapealready_claimedmanifest_not_foundpayload_too_largemodule_too_largeui_too_largestyles_too_largedescription_too_longmissing_descriptioninvalid_descriptionrate_limitedimage_origin_deniedtoo_many_requestsexpiredalready_approvedanon_not_remixabletemplate_listing_incompletetemplate_media_invalidtemplate_listing_too_largeforbidden_template_editinvalid_if_matchprecondition_requiredexpected_revision_requiredidempotency_key_requiredidempotency_conflictapp_build_capacityapp_build_failedapp_build_expiredapp_build_authority_lostapp_build_unavailableapp_build_unsupportedversion_history_unavailableversion_not_restorablerevision_mismatchinvalid_revisioncandidate_effects_unsupportedold_string_not_foundold_string_not_uniqueinvalid_bucketbucket_unsetempty_editsedits_too_largemanifest_id_conflictmanifest_id_immutabletext_too_largestructured_data_too_largeapp_not_foundfeedback_not_foundfeedback_has_no_reply_recipientasset_too_largeasset_count_exceededasset_quota_exceededasset_invalid_keyasset_invalid_content_typeasset_errorinvalid_idsse_cookie_expiredinvalid_secret_namesecret_too_largesecret_already_existssecret_not_foundinvalid_iconteam_slug_takenalready_membertwo_factor_requiredrecent_login_requiredgrantee_not_foundinvite_cap_reachedinvite_sender_blockedrole_above_owninvite_delegation_owner_onlynot_your_inviteread_onlyhandle_takeninvalid_handlename_takeninvalid_domaindomain_takendomain_existsdomain_provider_unavailableapp_unclaimedlink_cap_reachedgrantee_is_ownergrantee_is_selfgrantee_already_has_accessalready_invitedroutine_limit_exceededinvalid_intervalop_requires_inputduplicate_routinewebhook_limit_exceededduplicate_webhookwebhook_disabledversion_limit_exceededplan_requiredconnector_call_limit_exceededconnector_rate_limitedconnector_not_grantedconnector_action_not_declaredconnector_no_personconnector_reconnect_requiredconnector_unavailableconnector_tool_failedconnector_cross_siteconnector_blocked_by_teamconnector_route_not_declaredconnector_function_not_approvedconnector_version_retiredconnector_holder_onlystorage_limit_exceededcopy_data_forbiddencopy_data_too_largemessagestringreasonstringSet on 401s to distinguish token failure modes when finer detail is needed. token_revoked_post_claim is the post-#1284 surface for a chrm_app_* that was invalidated by a claim — the recovery field on the same error object carries the self-contained pairing-recovery hint the agent should follow instead of creating a new app.
token_malformedtoken_unknowntoken_revokedtoken_revoked_post_claimplanstringPresent on every plan refusal: the tier the caller was refused under. Its presence is what marks an error as a plan refusal rather than a validation or permission failure.
freeprobusinessenterpriselimitstring | integerWhich ceiling the call met, keyed by kind. A plan refusal (*_limit_exceeded) names the countable that ran out — version_history, routines_per_app, routines_per_owner, webhooks_per_app, webhooks_per_owner, connector_calls_per_month — and pairs it with max. An app_busy refusal names the bound it met and pairs it with observed and allowed; no plan lifts any of them. Two are per-app run bounds, concurrent_runs and runs_per_window; the third, render_token_refresh, is the page render asking for a new render-token secret, held by 10 per app per client IP and 60 per app across every address in a 60 second window, and observed/allowed name whichever of those two refused. An edits_too_large rejection carries the numeric cap that was exceeded instead of a name.
rungstringOn an app_busy refusal, how hard the app's own refusal ladder is refusing: throttled is the plain ceiling breach above; parked means a caller kept calling inside a wait it was given, so the server mints its own Retry-After (doubling from 60s to a 300s cap) and refuses until a quiet window passes even once the ceiling clears; closed is the same, plus the response closes the connection. Absent on every other kind.
throttledparkedclosedmaxintegerOn a *_limit_exceeded refusal, that limit's number on the caller's plan.
featurestringOn a plan_required refusal, the capability the plan does not include. Never paired with limit / max.
custom_domainwatermark_removalteamsupgradeUrlstring<uri>Absolute link to the owner's own billing page, where the refusal is lifted — the team's page for a team-owned app. Omitted only when the owner has no handle and therefore no settings page of their own, so treat it as optional and fall back to your own copy. MCP appends it as an Upgrade: <url> last line; the CLI prints it under the message.
missingLevelsstring[]On a connector_not_granted refusal, the access levels (in the order read, write, delete) the App's declared tools for the service need and the caller has not approved. Present only when approving would add something: call charming.connect(service) then. Absent means approving again would not help. On a refused PATCH /api/v1/apps/{appId}/connectors/{service}, the shared levels the holder's approval lacks instead.
recoveryRecoveryPair | RecoveryRetry | RecoveryShrink | RecoveryRefetch | RecoveryFixRouteLabel | RecoveryRename | RecoveryMigrateContractSelf-contained recovery hint, branching on kind. Attached to error envelopes the agent can self-correct on: pair for token_revoked_post_claim 401s (#1284), retry for 429s, shrink for too-large / quota-exceeded 413s, refetch for 412 revision_mismatch / invalid_if_match / 428 precondition_required, fix_route_label for 403 forbidden_write, rename for 409 manifest_id_immutable / manifest_id_conflict, and migrate_contract for 422 contract_migration_required. Every instructions string is a single-paragraph, action-first walk-through. Inlined per ADR 2026-05-06-agent-facing-error-surfaces-self-contain-the-fix.
Show propertiesHide properties
kindstringrequiredpairstartstring<uri>requiredverification_urlstring<uri>requiredinstructionsstringrequiredkindstringrequiredretryretry_after_secintegerrequiredSeconds to wait before retrying. Matches the RateLimit-Reset and Retry-After headers on the same response.
retry_after_urlstring<uri>requiredAbsolute URL to retry verbatim once the wait elapses.
instructionsstringrequiredkindstringrequiredshrinkfieldstringrequiredWhich input tripped the cap.
moduleuistylesdescriptiontextstructured_dataasseteditssecretpayloadsize_bytesintegerrequiredcap_bytesintegerrequiredinstructionsstringrequiredkindstringrequiredrefetchrefetch_urlstring<uri>requiredAbsolute URL to GET for the fresh ETag before retrying with a corrected If-Match.
instructionsstringrequiredkindstringrequiredfix_route_labelinstructionsstringrequiredApp-code recovery: the fix is in the route declaration, NOT in the request. Retrying the same request will fail again.
kindstringrequiredrenameinstructionsstringrequiredkindstringrequiredmigrate_contractinstructionsstringrequiredCharming cannot build packages right now (app_build_unavailable); retry later.
okbooleanrequiredfalseerrorobjectrequiredShow propertiesHide properties
kindstringrequiredStable enum-shaped error key. Branch on this for recovery flows.
not_foundunknown_operationoperation_not_foundmethod_not_allowedoperation_failedtimeoutapp_busyvisitor_rate_limitedservice_busyunauthorizedsign_in_requiredtoken_expiredforbiddenaccount_not_joinedstaff_onlytwo_factor_requiredreauthentication_requiredforbidden_writeview_as_read_onlyemail_not_verifiedemail_needs_sign_instored_value_too_largestorage_fulltoo_many_keysstorage_method_unavailableinvalid_moduleinvalid_uiinvalid_filesbearer_requiredunpinned_cdn_scriptinvalid_route_schemainvalid_routes_shapecontract_migration_requiredinvalid_manifest_schemainvalid_manifest_exportsinvalid_requestinvalid_inputinvalid_outputunexpected_keyscapability_deniedcapability_errorexecutor_errorinvalid_call_shapealready_claimedmanifest_not_foundpayload_too_largemodule_too_largeui_too_largestyles_too_largedescription_too_longmissing_descriptioninvalid_descriptionrate_limitedimage_origin_deniedtoo_many_requestsexpiredalready_approvedanon_not_remixabletemplate_listing_incompletetemplate_media_invalidtemplate_listing_too_largeforbidden_template_editinvalid_if_matchprecondition_requiredexpected_revision_requiredidempotency_key_requiredidempotency_conflictapp_build_capacityapp_build_failedapp_build_expiredapp_build_authority_lostapp_build_unavailableapp_build_unsupportedversion_history_unavailableversion_not_restorablerevision_mismatchinvalid_revisioncandidate_effects_unsupportedold_string_not_foundold_string_not_uniqueinvalid_bucketbucket_unsetempty_editsedits_too_largemanifest_id_conflictmanifest_id_immutabletext_too_largestructured_data_too_largeapp_not_foundfeedback_not_foundfeedback_has_no_reply_recipientasset_too_largeasset_count_exceededasset_quota_exceededasset_invalid_keyasset_invalid_content_typeasset_errorinvalid_idsse_cookie_expiredinvalid_secret_namesecret_too_largesecret_already_existssecret_not_foundinvalid_iconteam_slug_takenalready_membertwo_factor_requiredrecent_login_requiredgrantee_not_foundinvite_cap_reachedinvite_sender_blockedrole_above_owninvite_delegation_owner_onlynot_your_inviteread_onlyhandle_takeninvalid_handlename_takeninvalid_domaindomain_takendomain_existsdomain_provider_unavailableapp_unclaimedlink_cap_reachedgrantee_is_ownergrantee_is_selfgrantee_already_has_accessalready_invitedroutine_limit_exceededinvalid_intervalop_requires_inputduplicate_routinewebhook_limit_exceededduplicate_webhookwebhook_disabledversion_limit_exceededplan_requiredconnector_call_limit_exceededconnector_rate_limitedconnector_not_grantedconnector_action_not_declaredconnector_no_personconnector_reconnect_requiredconnector_unavailableconnector_tool_failedconnector_cross_siteconnector_blocked_by_teamconnector_route_not_declaredconnector_function_not_approvedconnector_version_retiredconnector_holder_onlystorage_limit_exceededcopy_data_forbiddencopy_data_too_largemessagestringreasonstringSet on 401s to distinguish token failure modes when finer detail is needed. token_revoked_post_claim is the post-#1284 surface for a chrm_app_* that was invalidated by a claim — the recovery field on the same error object carries the self-contained pairing-recovery hint the agent should follow instead of creating a new app.
token_malformedtoken_unknowntoken_revokedtoken_revoked_post_claimplanstringPresent on every plan refusal: the tier the caller was refused under. Its presence is what marks an error as a plan refusal rather than a validation or permission failure.
freeprobusinessenterpriselimitstring | integerWhich ceiling the call met, keyed by kind. A plan refusal (*_limit_exceeded) names the countable that ran out — version_history, routines_per_app, routines_per_owner, webhooks_per_app, webhooks_per_owner, connector_calls_per_month — and pairs it with max. An app_busy refusal names the bound it met and pairs it with observed and allowed; no plan lifts any of them. Two are per-app run bounds, concurrent_runs and runs_per_window; the third, render_token_refresh, is the page render asking for a new render-token secret, held by 10 per app per client IP and 60 per app across every address in a 60 second window, and observed/allowed name whichever of those two refused. An edits_too_large rejection carries the numeric cap that was exceeded instead of a name.
rungstringOn an app_busy refusal, how hard the app's own refusal ladder is refusing: throttled is the plain ceiling breach above; parked means a caller kept calling inside a wait it was given, so the server mints its own Retry-After (doubling from 60s to a 300s cap) and refuses until a quiet window passes even once the ceiling clears; closed is the same, plus the response closes the connection. Absent on every other kind.
throttledparkedclosedmaxintegerOn a *_limit_exceeded refusal, that limit's number on the caller's plan.
featurestringOn a plan_required refusal, the capability the plan does not include. Never paired with limit / max.
custom_domainwatermark_removalteamsupgradeUrlstring<uri>Absolute link to the owner's own billing page, where the refusal is lifted — the team's page for a team-owned app. Omitted only when the owner has no handle and therefore no settings page of their own, so treat it as optional and fall back to your own copy. MCP appends it as an Upgrade: <url> last line; the CLI prints it under the message.
missingLevelsstring[]On a connector_not_granted refusal, the access levels (in the order read, write, delete) the App's declared tools for the service need and the caller has not approved. Present only when approving would add something: call charming.connect(service) then. Absent means approving again would not help. On a refused PATCH /api/v1/apps/{appId}/connectors/{service}, the shared levels the holder's approval lacks instead.
recoveryRecoveryPair | RecoveryRetry | RecoveryShrink | RecoveryRefetch | RecoveryFixRouteLabel | RecoveryRename | RecoveryMigrateContractSelf-contained recovery hint, branching on kind. Attached to error envelopes the agent can self-correct on: pair for token_revoked_post_claim 401s (#1284), retry for 429s, shrink for too-large / quota-exceeded 413s, refetch for 412 revision_mismatch / invalid_if_match / 428 precondition_required, fix_route_label for 403 forbidden_write, rename for 409 manifest_id_immutable / manifest_id_conflict, and migrate_contract for 422 contract_migration_required. Every instructions string is a single-paragraph, action-first walk-through. Inlined per ADR 2026-05-06-agent-facing-error-surfaces-self-contain-the-fix.
Show propertiesHide properties
kindstringrequiredpairstartstring<uri>requiredverification_urlstring<uri>requiredinstructionsstringrequiredkindstringrequiredretryretry_after_secintegerrequiredSeconds to wait before retrying. Matches the RateLimit-Reset and Retry-After headers on the same response.
retry_after_urlstring<uri>requiredAbsolute URL to retry verbatim once the wait elapses.
instructionsstringrequiredkindstringrequiredshrinkfieldstringrequiredWhich input tripped the cap.
moduleuistylesdescriptiontextstructured_dataasseteditssecretpayloadsize_bytesintegerrequiredcap_bytesintegerrequiredinstructionsstringrequiredkindstringrequiredrefetchrefetch_urlstring<uri>requiredAbsolute URL to GET for the fresh ETag before retrying with a corrected If-Match.
instructionsstringrequiredkindstringrequiredfix_route_labelinstructionsstringrequiredApp-code recovery: the fix is in the route declaration, NOT in the request. Retrying the same request will fail again.
kindstringrequiredrenameinstructionsstringrequiredkindstringrequiredmigrate_contractinstructionsstringrequired