Start with what failed and what already exists. A source URL can be refused before a document is stored; a confirmation response can disappear after a dispatch was accepted. Those situations need different recovery. A generic retry loop cannot safely distinguish them.
Gather a small, useful observation
Record the time, affected surface, HTTP status, stable error code and correlation identifier. In a private support context, retain the existing document, dispatch or preflight reference and the action already requested. Keep credentials, signed URLs, recipient details, original content and raw request/provider bodies out of logs and public reports.
These public reads help separate an unavailable application from a disabled capability or a different release:
curl --fail --silent --show-error https://guteneo.com/api/health
curl --fail --silent --show-error https://guteneo.com/api/capabilities
curl --fail --silent --show-error https://guteneo.com/release.jsonInterpret each response independently. Health is not provider delivery proof; configured scanning is not proof of fresh signatures. Capability flags explain current gates, while the manifest identifies published source. Check the status service for its separately bounded public observations.
Sign-in, access or mutation refused
| Symptom | Safe check | Recovery boundary |
|---|---|---|
AUTHENTICATION_REQUIRED or SESSION_EXPIRED |
Check whether this is a browser session, native session or OAuth call | Reauthenticate through that client’s documented flow |
ORIGIN_REJECTED or CSRF_REJECTED |
Check the exact browser origin and current session/CSRF pairing | Correct the origin/session; keep the protections enabled |
INSUFFICIENT_SCOPE, revoked connection or changed membership |
Check current scopes, workspace binding, role and resource access | Reconnect or ask the authorized administrator; no client-supplied tenant switch |
A private 404 |
Check the existing identifier and the account/workspace actually connected | Absence and inaccessible content are intentionally not a global existence oracle |
For local browser work, use http://localhost:8787 consistently.
127.0.0.1 and localhost are different origins. A bearer token is not a browser
session and cannot be used to impersonate human approval.
Reconnecting an assistant can restore only its valid connection/scopes; it does not activate or renew an expert mandate. Use authority and tenancy for role and approval boundaries, or MCP integration for host-specific limitations.
A PDF source was refused
SOURCE_NOT_ALLOWED is an input/egress refusal before the service downloads and
stores the PDF. It is distinct from the verification state of a document already
returned by an earlier upload.
Check that the source is a real, unexpired direct HTTPS PDF download on the default port, without credentials, a fragment, redirects or a private/reserved host. A host attachment handle, local filesystem path or login page is not an accessible source. The service does not copy browser cookies or assistant account credentials to retrieve it.
Local URL import is deliberately disabled; use authenticated multipart upload. For an expired attachment link, obtain renewed access to the original bytes rather than reconstructing a PDF from extracted text or inventing another URL. Keep only the safe source-domain diagnostic for support, not the temporary signed URL. See documents and exact bytes for the import contract.
A stored PDF is still quarantined
Read the existing document’s analysis fields. Quarantine means required proof
has not completed; it is not itself a malware verdict. Follow nextAction and
any returned retryAfterSeconds instead of repeatedly importing the same file.
| Analysis result | Appropriate next step |
|---|---|
processing / wait |
Wait the returned interval, then read the same document; existing bounded background work needs no new upload |
retryable / rescan |
An authorized actor may explicitly restart analysis of that same original under the existing limits |
blocked / contact_support |
Keep the original and escalate the stated configuration, freshness, integrity or authority issue |
blocked / replace_document |
Obtain a compatible/corrected file as requested; preserve its separate identity and hash |
ready / continue |
Continue only with operations allowed for the current actor and document |
Missing service configuration, stale signatures and integrity failures must not be bypassed with a manual ready flag or an approval. A purged document cannot be revived by rescanning. Browser preview and Horizon diagnostics cannot supply the missing security proof.
If page-image review fails after readiness, preserve the document/dispatch reference and resolve the actual reader/renderer limit. Do not approve unreadable pages, create an unnecessary dispatch or request a mandate merely to read an otherwise accessible document. Human review remains an explicitly chosen path under its own authority.
A preparation or confirmation response was lost
First read the same operation. Keep the exact parameters and idempotency key for an idempotent replay under its contract; a new key describes a new intended operation and can create a duplicate.
| Existing dispatch state | Safe interpretation and next check |
|---|---|
prepared |
Inspect its exact quote, document and current approval; preparation created no transmission |
queued |
Acceptance/reservation/outbox have committed; inspect the existing work rather than preparing another dispatch |
submitting |
A provider attempt is in progress or awaiting its outcome; do not create a replacement |
submission_unknown |
Stop automatic resubmission; authorized provider-specific reconciliation is required |
accepted or a later channel state |
Read the recorded events; acceptance, delivery, postal handoff and settlement have distinct meanings |
failed or cancelled |
Inspect the actual attempt/event and cancellation limits before proposing any new communication |
An HTTP timeout does not prove that a provider rejected a request. A status refresh, page reload, queue redelivery or database restore grants no fresh sending authority. The dispatch lifecycle owns the full transition and reconciliation model.
An expired quote also needs an explicit contract, not a guessed deadline. The
linked fax-renewal path is eligible only when the returned state is prepared
and attemptCount is explicitly zero. A missing count is not zero. Preserve the
same document, recipient and ceiling; follow the returned renewal path and obtain
fresh review/approval for its new version. This does not generalize to email,
postal transfer or an uncertain provider attempt.
Configuration, quota or service capability is closed
Read the returned blocker and current capabilities. Missing identity, renderer, scanner, provider, sender, trusted pricing, billing entitlement or channel configuration must keep the affected path closed. Enough credit or a valid mandate does not satisfy the other gates.
For RATE_LIMITED, respect Retry-After and the relevant request budget. Content,
scan, account-credit and delegated budgets are separate limits. Resolving one
does not reset the others, and a write with an uncertain outcome still needs
state recovery before any replay.
Ask the authorized owner of the affected setting to review it through the existing administration flow. Do not automatically broaden scopes, activate a provider, change billing, extend a mandate or promise an available top-up. Platform Belvédère oversight helps inspect selected operational facts but creates no authority to repair a customer’s data or resend work.
Escalate with bounded evidence
Provide the stable error/correlation code, time, source/release, affected client, operation stage, relevant non-sensitive state and the safe checks already made. Explain whether the result came from local fixtures, CI, a hosted read or an authenticated journey. A small reproducible synthetic case is more useful than a raw production payload.
Stop when the missing evidence belongs to another boundary: current identity, scan freshness, hosted engine configuration, provider reconciliation or approved account administration. Escalation preserves the original identifiers and unknown state; it does not assert success, supply consent or create a replacement communication. For release-related mismatches and recovery scope, read changes and releases.