> For the complete documentation index, see [llms.txt](https://docs.mediafier.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mediafier.ai/connect/troubleshooting.md).

# Troubleshooting

Structured errors, retry guidance, and trace-id correlation for every refused call.

> **Every error is structured and traceable.** When a call is rejected, the gateway returns a typed error envelope carrying a `trace_id` — quote it when you ask for help, and a request can be correlated end-to-end.

***

## How errors look

A rejected call returns an error envelope with a stable `code`, a human-readable message, and a `trace_id`. Over MCP they arrive in the JSON-RPC `error.data` field.

***

## Common errors

| Code               | What it means                                                  | What to do                                                             |
| ------------------ | -------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `UNAUTHORIZED`     | You're not signed in, or the token is missing/expired.         | Sign in again from your client, or obtain a fresh access token.        |
| `FORBIDDEN`        | Authenticated, but not allowed — scope, role, or organization. | Check the credential's scopes and your organization membership.        |
| `PAYMENT_REQUIRED` | Your organization is out of credits.                           | Top up credits or check billing; then re-run.                          |
| `RATE_LIMITED`     | Too many requests in a short window.                           | Back off and retry; honor `Retry-After` when present.                  |
| `NOT_FOUND`        | The tool or resource isn't visible to your organization.       | List what's available first (`tools/list` / `resources/list`).         |
| `INTERNAL_ERROR`   | A transient server-side problem.                               | Retry with backoff; if it persists, share the `trace_id` with support. |

`RATE_LIMITED` can be resent after backoff: the call was refused before it ran. An upstream 5xx, a transport failure or a dispatch timeout is different. The operation may have completed, so the outcome is unknown. Do not repeat it automatically. Use the status or reconciliation action the error supplies, if there is one.

**Getting an access token fails?** The token endpoint answers with an OAuth error, before any call reaches Mediafier:

* `access_denied` / `Unauthorized` — the client ID or secret is wrong, or the credential was revoked or has expired. Check the value in your secret manager, or regenerate the credential.
* `access_denied` / "not authorized to access resource server" — the request asked for the wrong `audience`. Use the audience from the Agent Card (see [Authentication & Agent Credentials](/connect/authentication.md)).

**Can't find a tool?** Call the `list_commands` tool to see the curated command vocabulary; if a tool is missing there, use `tools/list` for everything available to your organization.

***

\| ------------------------------------------------------ | | `0` | Success. | | `1` | Generic failure. | | `64` | Usage error (unknown command or missing argument). | | `77` | Refused for a safety reason (e.g. wrong organization). | | `78` | Command exists but isn't available yet. |

***

## Connection issues

* **Wrong endpoint** — the only public ingress is `https://mcp.mediafier.ai/mcp` (or `/mcp/{server-slug}`). Other paths won't route.
* **Raw HTTP gets no stream** — send `Accept: application/json, text/event-stream` and reuse the session id returned by `initialize` on follow-on calls.
* **Harness won't sign in** — most harnesses open a browser on first use; for headless clients, exchange an Agent Credential for an access token (see [Authentication & Agent Credentials](/connect/authentication.md)).

***

## Getting help

Quote the `trace_id` from the error envelope (or the `X-Trace-Id` you sent). It lets support correlate your exact request across the platform.

***

## Next steps

* [Getting Started](/connect/getting-started.md) — connect, sign in, first call.
* [MCP Access](/connect/mcp-access.md) — connect a client and discover tools.