Errors and resource limits

Service calls can reject. Handle expected errors close to the user action, avoid logging sensitive payloads, and never weaken host validation to make a plugin work.

Common error families

Error	Response
capability_denied:<capability>	Declare and obtain approval for the required capability; do not bypass the host
plugin_api_update_required	Install compatible runtime and plugin builds
plugin_not_confirmed	Ask the user to review and enable the current bundle
plugin_identity_mismatch / plugin_export_missing	Fix the manifest/definePlugin identity or bundle registration
plugin_stopped	Ignore late results from the old instance
resource_limit / resource_not_owned	Release unused resources and use only current-instance handles
image_private_address / invalid_image_url	Supply a permitted public HTTPS PNG URL
image_too_large / image_dimensions_exceeded / image_invalid_png	Use an image within the supported policy
invalid_plugin_network / invalid_setting_definition	Fix the manifest: network needs matching network.hosts, and only string settings can be secret
invalid_network_request	Fix the request: HTTPS URL, allowed headers, body only with POST, within size limits
network_host_denied / network_redirect_denied / network_redirect_limit	Request, or redirect to, only listed hosts over HTTPS
network_private_address	The host must resolve to public IPv4 addresses
network_response_too_large / network_response_not_text / network_encoding_unsupported	The server must answer with uncompressed UTF-8 text of at most 256 KiB
network_timeout / network_failed / network_limit	Try again later, with fewer requests in flight
network_cancelled / plugin_changed	The plugin stopped or its code changed; ignore the result
attachment_context_expired / attachment_context_unavailable	Activate the posted-file menu again
attachment_lookup_busy	Avoid concurrent lookups for the same service instance
interaction_required	Request another real user activation
storage_quota_exceeded	Remove stored data; each plugin may store up to 1 MiB
user_gesture_required	Send or copy straight after a user action in the plugin’s UI
external_open_failed	Explain the failure and allow a fresh user-initiated attempt
badge_provider_exists	Dispose the current provider before registering another
badges_unavailable	The runtime can’t show badges on this page; skip the feature
guild_not_open	Only ask about the open community or ones opened this session
guild_data_unavailable / guild_data_timeout	Fluxer didn’t answer usefully; try again later or skip the feature
guild_data_rate_limited / guild_data_busy	Wait for earlier requests; FluxPlugs caches answers for 10 minutes
context_menu_unavailable / decorations_unavailable	The runtime can’t draw this on the page; skip the feature
decoration_provider_exists	Dispose the current provider before registering another
composer_unavailable / composer_insert_failed	No message box is open, or it refused the text; tell the user
settings_page_exists	Dispose the current settings page before registering another
view_busy	The frame is showing the plugin’s settings page; open the view after the user leaves it
voice_unavailable	The runtime can’t read the voice connection on this page; skip the feature
unknown_patch_hook:<hook>	Use one of the named hooks

Errors from individual host operations may be more specific. Avoid treating every rejection as a retryable network failure.

Limits that affect plugin design

Resource	Current bound
Plugin executable	2 MiB, single bundled entry
ZIP import	128 entries; 8 MiB compressed/total declared expanded content; 256 KiB manifest; 15-second deadline
ZIP compression	Stored or Deflate
Native dialog	12 sections; 32 controls per section; up to 25 repeat rows
Image request	8 seconds; 1 MiB; 3 redirects
Image dimensions	2048 per dimension and 1,048,576 total pixels
Images per instance	8 simultaneous/retained resources
Network hosts	1 to 16 per manifest
Network request	10 seconds; 8 KiB URL; 16 headers; 32 KiB body (POST only); 256 KiB text reply; 3 redirects
Network requests in flight	4 per instance; 32 plugin instances at once
Clipboard text	8192 characters
Plugin storage	1 MiB of JSON per plugin
Registrations per instance	64 in total across actions, menu items, pages, patches, providers and subscriptions
Right-click menu items	16 per instance
Message box text	4000 characters, no control characters except line breaks and tabs
Route changes	Noticed within 250 ms; only the newest waiting route is delivered
Idle time	60 to 3600 seconds per call or subscription, default 300
Settings page	1 per instance; title of 1 to 40 characters
Community data	Communities opened this session (last 20); 10-second fetch; 10-minute cache; 4 requests waiting
Decoration provider	1 per instance; batches of 25 places; 1-second answer; 2 batches waiting; 2 KiB of blocks per place
Decoration blocks	8 below a message (2 images, 4 buttons or links); 3 text or badge blocks next to a name
Message text	4000 characters per message, with message_content
badges.merge	Reorder or drop only; 6 badges
Attachment metadata	10 seconds; 1 MiB; 100 attachments
Attachment context	5 minutes maximum, invalidated earlier by relevant state changes
External navigation authorization	2 minutes, single-use
Named patch handler	1-second default timeout
Role badge provider	1 per instance; 1-second answer; 250 badges; labels of 1 to 12 characters; 1 to 5 badges per person
Embed fields	25

Further schema and JSON budgets apply. Validation occurs at multiple boundaries, so a well-typed TypeScript value can still be rejected.

Recovery pattern

Catch errors inside asynchronous actions, show a concise next step, and leave cancellation without side effects. Free resources when leaving a feature, not only at shutdown. Guard pending work with instance lifetime checks.

Testing and debugging describes exercising these failure paths.