Documentation

Automation

Troubleshooting

Resolve connection, permission, version, upload, and retry failures without bypassing safeguards.

Connection and Discovery

  • Use the full deployed /api/mcp URL with Streamable HTTP and the fixed Authorization header. A remote connector cannot reach your laptop's localhost.
  • If the client requires OAuth and cannot send fixed credentials, it is not compatible with the current connector. Do not remove server authentication as a workaround.
  • Refresh/reconnect after a deployment. Public reference availability does not mean the key is authorized for all listed tools.
  • Where required, allowlist www.usecoil.app in the agent's network settings. Confirm the current session's capabilities rather than relying on a product-wide assumption.

Common Failures

  • 400: inspect the input schema and cross-field rules. Do not invent IDs, dates, or file bytes.
  • 401: the credential is missing, expired, revoked, or its owner no longer has access.
  • 403: the key lacks a required scope, nested action permission, or allowed origin.
  • 404: the record or tool is unavailable in this workspace; do not probe other workspaces.
  • 409: stale versions, changed/expired previews, a used upload, or a conflicting request ID. Review current state before a new action.
  • 413/415: narrow the response/date range or respect file size and content-type limits.
  • 429: obey Retry-After. Keys allow 60 authenticated requests per fixed minute.
  • 500 or network interruption: inspect Coil and the request/audit state. Retry a write only with its original ID and identical arguments.

Upload Failures

A 403 from the agent's egress proxy is a network-policy issue, not necessarily a Coil permission error. Allow the exact returned upload hostname and do not follow redirects to another host. If the session lacks original-byte access, upload through Coil manually. A PUT that claimed its one-time URL before interruption needs a fresh upload request; do not reuse the spent URL. Reuse the receipt creation request ID after an uncertain create result.

Know What Is Not Exposed

Team access, key management, billing, global catalog moderation, workspace sales settings, removal reasons other than giveaways, and receipt merge/split are not agent operations in this release. Use appropriate manual UI workflows or request a supported extension; do not try arbitrary routes to bypass the tool boundary.