Protocol
Limits and errors
Widget extensions have strict resource limits. The app enforces all of the limits below. The Notes column says what the app does when a response is over a limit. The app rejects the response unless a note says that it drops the extra items or changes the value.
| Limit | Value | Notes |
|---|---|---|
| JSON body | 256 KB | The app measures the payload before it decodes it. The app rejects a larger payload and does not parse it. |
| Image body | 2 MB | Applies to `image` nodes and to bitmap responses. |
| Image pixels | 2000 px | On the longest side. |
| Nodes | 300 | Counted across the whole tree, including every entry. |
| Depth | 12 | How far stacks may nest. |
| Timeline entries | 60 | The app drops extra entries. This is not an error. |
| Entry spacing | 5 minutes | The app drops entries that are closer together, because WidgetKit ignores them. |
| Refresh | 300–86400 s | The app clamps values outside the range. It does not reject them. |
| Request timeout | 10 s | |
| Redirects | 3 | The app checks for HTTPS again at every redirect. |
Invalid payloads
A decode failure produces a specific message, not a generic one. If there is no cached response, the widget shows only the message, under a small “Couldn't load” heading. The previews below show this error view. The wording comes from the same engine as every other preview on this site.
{"v": 1, "view": {"type": "Marquee"}} {"v": 1, "view": {"type": "text"}} {"v": 1, "view": {"type": "text", "text": "x", "color": "3DDC84"}} {"v": 1, "view": {"type": "image", "url": "file:///etc/passwd"}} Decode errors
These cases come from web/conformance/decode-cases.json. Both test suites run
this corpus: the Swift decoder in the app and the Rust engine that draws the previews on
this site. Both implementations are tested against every message on this page.
| Case | Message |
|---|---|
| an unknown node type is refused, lowercased in the message | Unknown node type "marquee" |
| text without a text field is refused | Missing required field "text" |
| a five-digit hex value is refused | Invalid value for "color": #12345 |
| non-hex characters are refused | Invalid value for "color": #GGGGGG |
| a colour without the hash is refused | Invalid value for "color": 3DDC84 |
| font style values are case-sensitive | generic decoding error |
| timer without a date is refused | Missing required field "until" |
| timer style names the timer style, not a font style | generic decoding error |
| a date with no timezone is refused | generic decoding error |
| month 13 is refused | generic decoding error |
| day 32 is refused | generic decoding error |
| gauge without a value is refused | Missing required field "value" |
| an inverted gauge range is refused | Invalid value for "max": 2.0 |
| a zero-width gauge range is refused | Invalid value for "max": 5.0 |
| a non-http image scheme is refused | Invalid value for "url": file:///etc/passwd |
| a schemeless image url is refused | Invalid value for "url": example.com/a.png |
| a payload with neither view nor entries is refused | Response contained no "view" or "entries" |
| a payload without v is refused | Missing required field "v" |
| a future protocol version is refused rather than misread | Payload version 2 is newer than this app supports |
| a view nested one level too deep is refused | View tree nested deeper than 12 levels |
| a view one node over the limit is refused | View tree exceeds 300 nodes |
| the node budget spans every entry, not each one separately | View tree exceeds 300 nodes |
| padding that is neither a number nor an object is refused | generic decoding error |
| a padding edge that is not a number is refused | generic decoding error |
| w refuses any other string | Invalid value for "w": wide |
| an opacity over 100 is refused | Invalid value for "color": red/120 |
| an opacity with a sign is refused | Invalid value for "color": red/-5 |
| an empty opacity is refused | Invalid value for "color": red/ |
| a span without text is refused | Missing required field "text" |
| a text with neither text nor spans is refused | Missing required field "text" |
| text defaults must be an object | Invalid value for "text": footnote |
| a symbol without a name is refused | Missing required field "name" |
| an unknown symbol mode is refused | generic decoding error |
| a border object needs a colour | Missing required field "color" |
| a live gauge with only from is refused | Missing required field "until" |
| a live gauge with only until is refused | Missing required field "from" |
| a grid row with more cells than columns is refused | Invalid value for "rows": row 1 has 3 cells for 2 columns |
| a grid row object needs cells | Missing required field "cells" |
| an unknown overflow is refused | Invalid value for "overflow": hide |
| a preferredFamily that is not a string is refused | generic decoding error |
Where the table says generic decoding error, the payload is still refused. The two runtimes word the error differently. The corpus therefore asserts that the payload fails, and does not assert the wording.
Transport failures
| Condition | Message |
|---|---|
| Not HTTPS | you.example is not HTTPS |
| Credentials over plain HTTP | Refusing to send credentials over plain HTTP to you.example |
| Non-2xx status | Server returned HTTP 503 |
| Body too large | Response is 400000 bytes, over the 262144 byte limit |
| Wrong content type | Cannot render Content-Type "text/html" |
| Image too large | Image is 4000px on its longest side, over the 2000px limit |
| Undecodable image | Response was not a decodable image |
| Redirect loop | Exceeded 3 redirects |
Counting nodes
The 300-node limit counts the whole response, not each entry. A timeline of 12 entries with 30 nodes each has 360 nodes, and the app refuses it. If you generate rows in a loop, set a maximum for the loop.
Depth is counted the same way. The limit is 12 levels. If a layout is close to 12 levels, remove the containers that it does not need.