Errors and quotas
A call either succeeds or is refused with a code. The codes are the same over MCP and over the REST API.
What a refusal looks like
Over MCP, the result is marked as an error and carries three lines your assistant can read and relay: the code, what happened, and what to do next.
insufficient_credits
You need 5 credits and have 2.
Add credits or change plan: https://mairies.vosfichiers.com/app/billing
Over REST, the HTTP status gives the kind of refusal and the body gives the detail:
{
"error": {
"code": "insufficient_credits",
"message": "You need 5 credits and have 2.",
"request_id": "3f9c2a7d41be4c0f9a61d2e7c5b80a14",
"required": 5,
"available": 2,
"billing_url": "https://mairies.vosfichiers.com/app/billing"
}
}
Branch on error.code, which is stable; show error.message to a person. Keep request_id (also in the X-Request-Id response header): it is what support needs to find the call.
Refused before anything runs
Nothing is charged for any of these.
| HTTP | Code | What happened | What to do |
|---|---|---|---|
| 404 | not_found |
No tool has this name, or a tool looked for something that does not exist or is not yours (a job, for instance) | Check the name against the list of tools, or the identifier |
| 405 | method_not_allowed |
Wrong HTTP method | Tools take POST; the catalogue, jobs and /me take GET |
| 503 | unavailable |
The tool is switched off, or the service is under maintenance | Try again later |
| 429 | locked_out |
Ten refused credentials from your address in ten minutes | Fix the key, then wait for retry_after seconds (fifteen minutes at most) |
| 401 | invalid_credential |
The key or token is unknown, revoked or expired | Create a new key, or connect the client again |
| 401 | auth_required |
A paid tool, or any MCP call, was sent without a key or token | Send Authorization: Bearer … |
| 403 | account_suspended |
The account is suspended | Write to support |
| 429 | rate_limited |
More calls in a minute than your plan allows | Wait for retry_after seconds; limit is your rate per minute |
| 422 | idempotency_conflict |
The idempotency key was already used with another body | Use a new key for a new request |
| 409 | idempotency_in_progress |
A call with this idempotency key is still running | Wait for it, then retry |
| 400 | invalid_json |
The body is not a JSON object | Send the arguments as a JSON object |
| 422 | invalid_input |
An argument is missing or wrong | Read fields: one entry per argument, with the reason |
| 402 | insufficient_credits |
The tool costs more than you have | required and available give the figures; add credits at billing_url |
Refused after the call started
The price of the tool was taken when the call started; each of these gives it back in full.
| HTTP | Code | What happened | What to do |
|---|---|---|---|
| 422 | tool_error |
The tool cannot do what was asked with these arguments (a video without transcript, an unknown code) | Read the message, change the request |
| 502 | upstream_error |
The service the tool relies on refused or failed | Retry later; after retry_after seconds when it is given |
| 504 | timeout |
The tool did not finish in time | Retry once |
| 500 | internal_error |
Something broke on our side. We are told automatically | Retry later; give the request_id to support if it lasts |
Rate limit
Each account may make a number of calls per minute set by its plan; GET /api/v1/me and your billing page show it. The limit is shared by everything that calls on your behalf: your assistants over MCP, your scripts over REST and the playground.
The allowance refills continuously, not at the turn of the minute: after a burst, calls are accepted again one by one as time passes. A refused call says how long to wait:
{
"error": {
"code": "rate_limited",
"message": "Too many calls: this plan allows 30 per minute.",
"request_id": "3f9c2a7d41be4c0f9a61d2e7c5b80a14",
"retry_after": 2,
"limit": 30
}
}
Over REST the same delay is in the Retry-After response header. Wait that long before retrying; retrying sooner is refused again. A call refused for its rate costs no credit.
Invalid arguments
invalid_input lists every argument that was refused. The values you sent are never echoed back.
{
"error": {
"code": "invalid_input",
"message": "Invalid arguments. url: Field required",
"request_id": "3f9c2a7d41be4c0f9a61d2e7c5b80a14",
"fields": [{"field": "url", "message": "Field required"}]
}
}
The page of each tool in the documentation gives the type, the bounds and the default of every field. You can also try a call in the playground before writing code.
Retrying
rate_limited,locked_out,upstream_errorwithretry_after: wait that long, then retry.timeout,upstream_errorwithout a delay,internal_error,unavailable: retry a little later, a few times at most, waiting longer each time.- Anything else: retrying the same request gives the same refusal. Change the request, the key or the balance first.
Over REST, send an Idempotency-Key header when a retry must never be charged twice: see Use the REST API.