Errors and recovery
Keep the work. Resolve the specific blocker.
A failed connection must not turn into fixture success. A failed destination must not erase successful posts. Recover from the recorded state and preserve the operation ID.
The codes below match the proposed v0.1 shared error schema. Backend agreement and live private API validation remain pending. The separate public discovery API is implemented and returns RFC 9457 JSON errors for unsupported routes and methods.
| Condition | What to do |
|---|---|
unauthenticated | Sign in or supply a valid scoped connection token. Never substitute a provider secret. |
forbidden | Check workspace membership and scope. Ask the owner for the specific authority needed. |
revision_conflict | Read the latest item, compare changes, then retry with its current revision. Preserve unsaved input. |
approval_required | Open the exact review URL returned by the backend. A model assurance cannot replace approval. |
stale_manifest | Prepare and review a new immutable schedule manifest for the edited content. |
idempotency_conflict | Do not reuse an operation key with different input. Reconcile the earlier request first. |
quota_exceeded | Inspect remaining measurable units and existing reservations. Retrying does not reset limits. |
unsupported | Read current capabilities and choose a supported format/channel combination. |
provider_unavailable | Read the provider error. If reconnection is required, have an authorized person reconnect the named account; retry only eligible failed targets. |
validation_error | Correct the reported field. For an expired schedule, choose future times and obtain fresh authorization. Never silently publish now. |
unknown_outcome | Poll/reconcile with the provider correlation ID. Do not create a duplicate post. |
When requests are throttled
Honor the returned retry hint or Retry-After; avoid concurrent retry loops. The live HTTP rate-limit response still needs verification.
When a request times out
Read the existing operation by its stable ID or repeat the original request with the same operation key and identical payload. A side-effecting retry must return the existing operation, not start a second render or post. A timeout is not proof that nothing happened.
When only one channel fails
Inspect each target separately. Keep provider-accepted and published destinations intact. Reconnect or edit the failed target as required, and retry only when the backend marks that job eligible. A changed provider-accepted post needs a new version and explicit cancellation/rescheduling when supported.
When preview media expires
Refresh the authorized media reference. Do not replace the current revision with an older asset, expose a private storage bucket, or show a completed state without playable media.
Useful details to retain
Keep the campaign/item ID, revision, operation/job ID, timestamp, error code, and provider correlation ID. Keep tokens, private payloads, cookies, and signing URLs out of diagnostic logs and support messages.