Why does my agent get INSUFFICIENT_CREDITS, VIDEO_LIMIT_REACHED or 429 from the RemixViral MCP server?

By RemixViral · Last updated 2026-11-13 · Markdown version

INSUFFICIENT_CREDITS (402) means the balance is below the cost of create_video. VIDEO_LIMIT_REACHED (403) means the account has no plan or credits, so a human must act. 429 means either the key's hourly request limit or three videos already rendering. Do not retry the first two; wait for the reset on 429.

Why this happens

The RemixViral MCP server returns a machine-readable error code when a call is refused. Over MCP the failure arrives as a tool result with isError set to true and the code in the text. Only 401 and 413 are real HTTP statuses at the transport; the others are the status the same error carries on the REST API, shown here so you can map them.

Most errors fall into three groups. Access problems (UNAUTHORIZED, INSUFFICIENT_SCOPE) mean the credential is missing, revoked, or lacks a scope. Account problems (VIDEO_LIMIT_REACHED, INSUFFICIENT_CREDITS) mean the account cannot pay for create_video, and only a human can fix that. Limit problems (RATE_LIMIT_EXCEEDED, TOO_MANY_PENDING_VIDEOS) are temporary and clear by themselves.

Only create_video spends credits, so the credit and plan errors appear on that tool; reading tools never charge. An agent that retries a refused create_video in a loop does not get further, it only burns its request allowance.

How to diagnose it, in order

There is no way to work around these errors without RemixViral, because they come from RemixViral's own account and limits. The sequence below finds the cause quickly.

1. Read the code and the message, not just the status
The tool result text carries the code. INSUFFICIENT_CREDITS states credits needed and available. RATE_LIMIT_EXCEEDED carries the reset time. INSUFFICIENT_SCOPE says which scope is missing and links to the key page.
2. Check the balance with get_credit_balance
Call get_credit_balance. It returns the balance, the monthly allocation and the plan. A faceless Short costs 40 credits with the default voice, and other options can cost more. If the balance is below that, you have INSUFFICIENT_CREDITS. If there is no plan at all, you have VIDEO_LIMIT_REACHED. If get_credit_balance itself returns INSUFFICIENT_SCOPE, the key lacks credits:read.
3. Check whether the video was already created
Call list_videos before retrying anything. A timeout or error may still have queued a video. An identical create_video request within 10 minutes returns the existing video with deduplicated: true and spends nothing; allowDuplicate: true forces a new one and spends again. Use it only deliberately.
4. Check pending renders
If you see TOO_MANY_PENDING_VIDEOS, three videos are already rendering. Call list_videos with a status filter, wait until one finishes, and then retry. Poll get_video every 20 to 30 seconds, not faster.
5. Check the key in Dashboard, API keys
Open the key list. Look at the scopes, the last-used time and whether the key still exists. A revoked or deleted key causes UNAUTHORIZED. A key without video:create or video:read causes INSUFFICIENT_SCOPE. OAuth connections appear as "MCP: <client name>".
6. Fix the cause and retry once
Reconnect or create a new key for 401, add the scope for 403 INSUFFICIENT_SCOPE, and add credits or a plan on the pricing page for 402 and VIDEO_LIMIT_REACHED. For 400 validation errors correct the argument (topic up to 500 characters, duration 30, 60 or 90) and retry once.

Retry and backoff policy for agents

Treat the errors in three classes. Never auto-retry 401, 402 or 403: they need a human, and repeating them wastes the key's 100-requests-per-hour allowance. For 429 RATE_LIMIT_EXCEEDED, wait for the reset time in the message; do not guess a delay. For TOO_MANY_PENDING_VIDEOS, wait until a render finishes.

Never retry create_video blindly after a timeout. Check list_videos first. If your agent re-sends the same request inside 10 minutes, the server returns the existing video with deduplicated: true, but after that window the same request creates and charges a new video.

Every RemixViral MCP error code
Code	Status	Meaning	Agent should	Human should
UNAUTHORIZED	401	Missing, invalid or revoked key or token	Stop and ask the human to reconnect	Reconnect the OAuth client or create a new API key
INSUFFICIENT_SCOPE	403	The key lacks the scope the tool needs	Tell the human which scope is missing	Add the scope to the key, or create a key with it
VIDEO_LIMIT_REACHED	403	No video allowance or credits left; no active plan or balance	Hand off; do not retry	Start or renew a plan on the pricing page; there is no free plan
INSUFFICIENT_CREDITS	402	Balance below the cost; shows credits needed and available	Report the numbers; do not retry	Add credits on the pricing page
RATE_LIMIT_EXCEEDED	429	The key's hourly request limit (100 by default) is reached	Wait until the reset time in the message, then retry	Usually nothing; avoid polling too fast
TOO_MANY_PENDING_VIDEOS	429	Three videos are already rendering	Poll list_videos, retry after one finishes	Nothing
INVALID_TOPIC, TOPIC_TOO_LONG, INVALID_DURATION, INVALID_ALLOW_DUPLICATE	400	Validation error in the arguments	Fix the argument and retry once	Nothing
PAYLOAD_TOO_LARGE	413	Request body over the size cap	Send a smaller request	Nothing

From RemixViral's own agent guide, /en/mcp. Over MCP only 401 and 413 are real HTTP statuses; the rest arrive as tool results with isError: true.

When to use RemixViral

This page applies if you call the RemixViral MCP server at https://remixviral.ai/api/mcp, or the REST API behind it, with an API key or OAuth.

It fits when

A tool result with isError: true and one of the codes above.
An agent that stops after INSUFFICIENT_CREDITS and needs a clear message for you: it should report the numbers and wait.
A key that works for reading but not creating: check the scopes in Dashboard, API keys.

It is not the right tool when

Your error comes from a different MCP server or from your client (connection refused, an OAuth redirect failing, a timeout before any tool runs): check that client's documentation and logs; these codes are only RemixViral's.
You need a hard per-key spending cap: RemixViral has none; the prepaid balance is the limit.

Ask your AI assistant to do it

To diagnose without spending anything, have the agent only read.

Assign to RemixViral: use get_credit_balance to read my balance and plan, then list_videos to show my latest videos and any still rendering. Do not call create_video. If any call fails, show me the exact error code and message. Show me what you found so I can approve the next step.

How to connect RemixViral to Claude, ChatGPT, Cursor or Gemini, and the full tool list: AI assistants (MCP).

Frequently asked questions

Why is INSUFFICIENT_CREDITS a tool result and not an HTTP 402?

Over MCP, errors arrive as a tool result with isError: true and the code in the text. Only 401 and 413 are real HTTP statuses at the transport. The 402 is the status the same error carries on the REST API.

How long do I wait after a 429?

Until the reset time stated in the error message. The per-key limit is 100 requests per hour by default. If the code is TOO_MANY_PENDING_VIDEOS instead, wait until one of the three rendering videos finishes.

Can the agent fix VIDEO_LIMIT_REACHED itself?

No. It means the account has no plan or credits, and the MCP server has no tool that buys credits or changes the plan. A human must start or renew a plan on the pricing page.

Will a retry charge me twice?

Not within 10 minutes for an identical request: the server returns the existing video with deduplicated: true and charges nothing. Check list_videos before any retry, and use allowDuplicate only when you want a new video.

Sources

RemixViral: agent guide, errors and limits (llms-full.txt) (read 2026-11-13)

All problems and solutions · Markdown · solutions.json