Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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).

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).

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

PreviousAgent-First Access
NextCompatibility

Last updated