Timeouts and expiry

The iframe integration has seven timers. Each has one clear action when it runs out.

All timers

Timer	Length	Who enforces it	When it runs out
Launch code, in `iframe_url`	120 seconds, one use	Flume	The iframe shows "Flume didn't open." with a retry
Ready timer	15 seconds	Your page	Remove the iframe. Show an error with a retry
Connect code	120 seconds, one use	Flume	`401` `CONNECT_CODE_INVALID`. The user verifies again on the next open
Save reply	60 seconds	The iframe	The iframe treats the save as failed
Instant quote wait in the iframe	About 18 seconds, then polling	The iframe	The iframe keeps the user informed. You do nothing
Iframe session	12 hours from the session's first open	Flume	`flume:close_iframe` with reason `expired`
Idle session state	30 days	Flume	The next open starts fresh

The iframe did not load

There are two kinds of failure. They show in different ways.

While the iframe opens, show your own way to close it, for example a Close button after a few seconds. The user is never stuck behind a blank frame.

The frame never loads. No flume:iframe_ready arrives, and your ready timer fires.

Call stop() and remove the iframe. A frame left in place can still finish loading with nobody listening.
Show "Flume did not load" with a retry button.
On retry, call POST /start-iframe-session again. Never reuse the old iframe_url.

Cause	Sign
Your page's origin is not an allowed origin	The frame is blank. The browser console shows a `frame-ancestors` error
Your CSP has no `frame-src` for the iframe origin	The browser console shows a `frame-src` error
`host_origin` is not this page's exact origin	The iframe shows and works, but no message reaches your page
`flumeOrigin` is wrong in your snippet	The iframe shows, but your page drops its messages
The network, or a slow first load	Nothing shows in time. Offer a retry

The frame loads but cannot start. The iframe posts flume:iframe_ready and shows its own error, "Flume didn't open.", with a retry. Your ready timer does not fire.

Cause	What happens next
`iframe_url` was used late or twice	The user presses "Try again". The iframe posts `flume:close_iframe` with reason `expired`. Start a session again

The session expired

The iframe posts flume:close_iframe with reason: "expired" when:

12 hours have passed since the session's first open,
the user's access token was revoked or replaced,
the user pressed "Try again" after a failed start.

Do this:

Remove the iframe.
Call POST /start-iframe-session again with the same user, project and item.
Mount the new iframe_url.

The user lands where they were. See How the iframe works.

Reopening the same item does not restart the 12 hours. They run from the session's first open.

The user access token stopped working

POST /start-iframe-session returns 401 USER_TOKEN_INVALID when the token you sent is unknown, revoked or replaced.

Delete the stored token.
Call again without X-Flume-User-Token.
The iframe asks the user to verify. Exchange the new connect code and store the new token.

A save got no reply

If your page does not reply in 60 seconds, the iframe shows a retry.

"Try again" sends flume:save_item again with the same save_uuid.
If your first write did succeed, reply flume:item_saved without writing again.
A reply without the right save_uuid counts as no reply.

The connect code expired

POST /users/exchange-connect-code returns 401 CONNECT_CODE_INVALID for a code that is spent or older than 120 seconds.

The user is still verified in the open session.
You hold no working token, so the user verifies again on the next open.
Exchange the code as soon as the message arrives. Do not queue it.

Image links expired

Image links in the save payload last about 24 hours. In the sandbox they can stop working earlier. Copy the bytes when you save. See Fetch an image.