Contents

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_error with retry_after: wait that long, then retry.
  • timeout, upstream_error without 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.