> 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`. From the SDK these become a typed `GovernedSDKError` (see [TypeScript SDK](/connect/typescript-sdk.md)); over raw 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.         | Re-authenticate (`mediafier auth login`) 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 (the SDK's `withRetry` does this for you).            |
| `NOT_FOUND`        | The tool or resource isn't visible to your organization.       | List what's available first (`mediafier tools list` / `resources/list`). |
| `INTERNAL_ERROR`   | A transient server-side problem.                               | Retry with backoff; if it persists, share the `trace_id` with support.   |

Transient failures (`RATE_LIMITED`, upstream 5xx, transport hiccups, dispatch timeouts) are safe to retry with backoff. The SDK's `withRetry` and `isRetryable` handle exactly this set.

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

***

## CLI exit codes

When scripting, branch on the CLI's exit code:

| Code | Meaning                                                |
| ---- | ------------------------------------------------------ |
| `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) — install, connect, first call.
* [MCP Access](/connect/mcp-access.md) — connect a harness and discover tools.
* [TypeScript SDK](/connect/typescript-sdk.md) — typed errors and retries.