Fileaify agent API — Errors — Failure handling

Part of the Fileaify agent protocol. Start page and index: /agent. Everything in one document: /agent/full.

Handle failures and termination

• HTTP 409 no_match and ambiguous_match for both section reads and edits; HTTP 409 result_unchanged for edits. For a section error, select an exact heading from the outline. For edits: reread the document and recompose the edit using its current revision. no_match includes a nearby-line suggestion; it is informational, never applied automatically. ambiguous_match includes the occurrence count.
• HTTP 409 line_too_long: increase limit_chars up to 45,000 or split the line; do not retry the same offset with the same limit.
• document_too_large is an advisory attention code, not a read failure. Split oversized active documents or archive obsolete history; the advisory threshold does not prohibit publication.
• HTTP 409 idempotency_conflict: do not reuse a key for a changed request. idempotency_unverifiable: inspect the legacy proposal before creating another.

Errors return a JSON error code. HTTP 400 means invalid input or an expired pairing; 401 means missing/invalid/expired/suspended/revoked credentials; 403 means insufficient permission; 404 means absent or inaccessible context; 409 means a conflict (read its code); 429 means rate limited; 503 means an integration is not configured. Never work around a denial.

On revision_conflict or contract_changed, reload the documents and contract, reconcile concurrent edits, and create a new proposal with a new idempotency key. On a temporary transport failure, retry only a safe read or the exact idempotent proposal, with bounded backoff. Preserve the user's work; do not repeatedly resubmit rejected changes.

Organization owners and administrators configure external-agent publication in Project settings, on every plan. Human review is the default; automatic publication may apply to selected agent identities or all agents retaining write access. Policy changes never accept existing pending proposals, and automatic publication never bypasses an existing lock or revision conflict. Archiving resets the policy to human review; restoring a project does not restore automatic trust.

Users can suspend/resume agents or revoke their individual grants from the web interface or dedicated remote-control PWA at https://fileaify.com/remote. The installation page is https://fileaify.com/remote/install. The mobile app shows the selected workspace’s authorized inbox, document-by-document diffs and human decisions; it does not load the full website. Web Push can notify subscribed devices while the app is closed, subject to browser/OS support and notification permission. Offline mode shows a connection screen without caching project documents or queuing decisions. The web interface has a right-hand “Pending requests” drawer, grouped by project, for access decisions, documentary reviews and revocable agent grants. The counter includes only decisions the current human may take in the active organization. Opening a pairing link or entering its code presents that pairing to the human; anonymous pairing requests are never broadcast across organizations. Approvers can review new requests without leaving their work. Dismissing a notification does not decide the request. The human-only /api/v1/inbox is not available to agent tokens; agents should keep using GET /api/v1/access-requests to check their own requests. Human approvals use the same permissions on both. Humans may accept or reject individual documents within a proposal. Each reviewed document is immediately published or rejected and its lock released; other documents remain pending. GET /api/v1/projects/{project_id}/changes exposes each item’s status and a mixed flag for differing decisions. Human decisions may supply document_ids alongside decision; omitting it decides all remaining items. A closed mixed proposal has aggregate status accepted if any item was accepted: inspect item statuses, never assume all documents were published. Pending items hold exclusive document locks until their approval or rejection. document_locked (409) means wait for the owner to resolve the existing transaction; do not bypass it. Agents cannot administer organizations, approve grants/contributions or invoke the Premium assistant. Premium global chat is read-only; a human can configure project chat in Plan, Ask or Autonomous mode with separate transaction validation. These human controls do not change external-agent permissions. Scheduled semantic reviews only produce reports.