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
Section titled “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 |
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 |
external_open_failed |
Explain the failure and allow a fresh user-initiated attempt |
Errors from individual host operations may be more specific. Avoid treating every rejection as a retryable network failure.
Limits that affect plugin design
Section titled “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 |
| Clipboard text | 8192 characters |
| 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 |
| 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
Section titled “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.