Troubleshooting

Common problems

The client cannot connect, or gets 401

The API key is missing, mistyped, or revoked. Check that ARGIL_API_KEY is set in the shell that starts the client, or create a new key in Workspace settings → API keys. A chat app that says “This sign-in request has expired” took too long to sign in: connect again.

The assistant uses the wrong workspace

One connection uses one workspace: an API key’s, or the one you picked when signing in. Disconnect and connect again with the other workspace, or use a key created in it.

A video seems stuck

Videos take minutes. Ask “check on my last Argil video”: the generation kept running even if the conversation stopped. You also find it in your Argil playground.

"Plan required" or "insufficient credits"

Generating needs an active Argil plan and enough credits in the workspace. Both are managed in the Argil app; everything else works without them.

The client asks before every check on a video

Allow the read tools (get_generation, get_asset, list_*) in your client’s settings. Keep approval on for generate_media, which spends credits.

The assistant cannot use a file I attached

Chat apps do not pass attachments to Argil. Upload the file in your Argil library and say “use my latest upload”, or give a public link.

Error codes

A refused tool call returns isError: true with the reason, and nothing is created or charged. The assistant reads it and usually fixes the call itself.

`code`	Meaning	What to do
`parameter_invalid`, `parameter_missing`, `parameter_unknown`	A field is wrong for that model; the answer gives the allowed values	Fix the field (`get_model` with the mode lists them)
`model_not_found`, `mode_not_supported`	The model or mode does not exist, or is not enabled in your workspace	Pick another with `search_models`
`reference_not_found`, `reference_not_allowed`	Unknown asset or element, or a file this mode cannot use	Find the right one with `list_assets` or `list_elements`
`asset_not_ready`, `asset_not_uploaded`, `url_unreachable`	A file is still processing, was never uploaded, or its URL cannot be downloaded	Wait with `get_asset`, upload it, or use a public link
`credit_limit_exceeded`	The price is above `max_credits`	Raise the budget, or pick cheaper options
`insufficient_credits`, `plan_required`	Not enough credits, or no active plan	Manage them in the Argil app
`idempotency_key_reused`, `idempotency_key_in_use`	The key belongs to another request, or its first call is still running	Use a new key, or retry a few seconds later
`resource_not_found`	No such id in your workspace	List to find the right id
`generation_not_terminal`, `too_many_webhook_endpoints`, `payload_too_large`	A running generation cannot be deleted; the workspace has too many webhook endpoints; an inline file is over 2 MB	Wait; delete an endpoint; use a URL or an upload
`rate_limited`, `too_many_queued_generations`, `too_many_asset_imports`	Too much at once	Wait and retry
`internal_error`, `service_unavailable`	A problem on Argil’s side	Retry after a short wait

A generation that starts and then fails, for example on moderation, is not an error code: it ends with status: failed and a reason, and its credits are refunded.

Security and privacy

One workspace. A connection works only on its workspace’s models, library, elements, credits and webhook endpoints.
No account access. An assistant cannot read or create API keys, change your plan or settings, or buy credits.
Spending is capped by you. Only generate_media spends credits; max_credits caps each generation.
Keys. Use one key per agent or machine, keep it in an environment variable or a secret store, never in a prompt. Revoking a key stops it at once; generations already running finish.
Private networks are out of reach. A URL you give is downloaded by Argil’s servers, only from public addresses.
What is logged. Each call’s tool, duration, outcome, workspace and key. Not your prompts, inputs or results: they stay in your workspace, as in the app.
Text from your workspace (prompts, names, descriptions) is returned as data, never as instructions to the assistant.

Technical details


URL	`https://mcp.argil.ai/mcp`
Transport	Streamable HTTP, stateless
Authentication	`Authorization: Bearer <API key>` (or `x-api-key`), or OAuth 2.1 starting at `https://mcp.argil.ai/.well-known/oauth-protected-resource/mcp`
Longest call	About 40 seconds (`wait_seconds`); longer work returns `processing`
Rate limits	60 writes and 600 reads per minute per workspace
Request size	4 MB; inline files up to 2 MB, uploads up to 2 GB
Browsers	Requests from web pages (a browser `Origin`) are refused

Get started

Guides

Reference

Troubleshooting

Common problems

Error codes

Security and privacy

Technical details

​Common problems

​Error codes

​Security and privacy

​Technical details

Common problems

Error codes

Security and privacy

Technical details