Error handling
Interact reports failed requests through $server.error and pauses automatic updates. Local edits remain available.
<p role="alert" x-text="$server.error ? $server.error.message : ''"></p>Ordinary actions need no .catch() callback. The persistent alert can announce changed messages. Put padding or a background on a wrapper shown only while an error exists if the empty alert should take no visual space.
Failure fields
error is null or { code, message, status, recovery }. A null status means no readable response was available. Recovery values are retry, reload, authenticate, or none; none performs an automatic action.
| Code | Meaning | Recovery |
|---|---|---|
snapshot_expired | The signed snapshot passed its lifetime | Reload |
session_changed | The snapshot belongs to a different session | Reload |
invalid_snapshot | Malformed, tampered, or wrong-scope snapshot | Reload |
unauthenticated | Authentication is required (401) | Application sign-in flow |
csrf_failed | CakePHP rejected the security token (403) | Reload |
forbidden | Current access is denied (403) | Application decision |
upload_too_large | Server rejected an oversized upload (413) | Choose a smaller file, then submit explicitly |
invalid_request | Update input was rejected (400) | Correct input, then explicitly try again |
server_error | Server returned a 5xx response | Verify the outcome before another explicit attempt |
http_error | Another HTTP error status | Application decision |
network_error | Fetch failed without a response | Verify the outcome before another explicit attempt |
unexpected_redirect | The update redirected instead of returning its protocol | Reload / check application authentication handling |
invalid_response | Invalid JSON, content type, envelope, identity, or root markup | Reload / check application logs |
client_error | The browser could not prepare or apply the update | Reload / check browser diagnostics |
Recovery
After a failure, queued actions and pending debounce timers are cancelled. For a retry failure, an explicit action, submit, or sync sends a fresh request with the current draft. It does not replay failed work. Other categories require an application decision, fresh mount, or sign-in flow.
<button
type="button"
x-show="$server.error && $server.error.recovery === 'retry'"
@click="$server.sync()"
:disabled="$server.busy"
>
Synchronize draft
</button>A failure may occur after a save completed. Verify the outcome before repeating a persistent operation. Offer a normal application reload/sign-in link where appropriate. exportDraft() supports an intentional copy step; there is no automatic browser storage or restoration.
Validation errors
A renderable HTTP 422 supplies $server.errors and does not pause updates. It is an accepted render rather than a request failure.
JavaScript and events
Inspect the RequestResult returned by call() or sync() when needed. The bubbling interact:error event contains the same failure fields and fires once per failed request, not for each blocked attempt. Removed islands do not emit new failure UI.
Server integration
The plugin subscribes to CakePHP's Exception.beforeRender event and returns safe versioned JSON for update exceptions after normal logging. Other routes and application-handled responses retain their handling. Custom error documents get status-based feedback; exception messages are not parsed to classify failures. Raw error pages and traces are not inserted into island HTML. See custom endpoints for route scope requirements.