Errors

Almost every failure arrives as a normal MCP tool result with isError: true and a plain-English message written for the assistant to relay to the user. The one exception is the rate limit, which is an HTTP 429. Messages below are quoted from the server.

Where a message contains a value that varies (a number, a name), it is shown in <angle brackets> or as an example.

No key, or key rejected

A painting tool called with no key, a mistyped key, or a revoked key.

No key (also returned when the Authorization header is not a muro_sk_… token, because such headers are ignored):

Painting a photo needs a Muro account with credits. Create an API key at https://app.usemuro.com/ustawienia (Settings → API keys) and add it to this connection as the header "Authorization: Bearer muro_sk_…". Looking up paint colours stays free without a key.

Key rejected (a well-formed key that Muro does not accept):

The Muro API key was rejected (missing, mistyped or revoked). Painting a photo needs a Muro account with credits. Create an API key at https://app.usemuro.com/ustawienia (Settings → API keys) and add it to this connection as the header "Authorization: Bearer muro_sk_…". Looking up paint colours stays free without a key.

Fix: create a new key and update the client. See API keys. If an assistant connected through Sign in with Muro, a revoked connection ends here too: reconnect it.

On /account/mcp, a client that has no valid OAuth token gets an HTTP 401 and starts the sign-in flow.

Insufficient credits

Checked before anything is uploaded or spent:

This needs <cost> credits (<n> colours × <per colour> in <quality>) and the account has <balance>. Top up or change plan at https://app.usemuro.com/plan.

For example: This needs 6 credits (2 colours × 3 in ultra) and the account has 4. Top up or change plan at https://app.usemuro.com/plan.

If the balance changes between the check and the start of painting, Muro can refuse with:

Not enough Muro credits for this. Each colour costs 1 credit in Standard, 2 in HD and 3 in Ultra. Top up or change plan at https://app.usemuro.com/plan.

The CLI checks first and prints This needs <cost> credits and you have <balance>. Top up at https://app.usemuro.com/plan. Prices: Pricing and limits.

Plan does not allow the quality

HD needs Pro and Ultra needs Premium. Muro returns its own reason. If it gives none, the fallback is:

This quality is above the account’s plan. Try quality "standard", or upgrade at https://app.usemuro.com/plan.

Fix: use quality: "standard", or upgrade.

Photo problems

Cause	Message
Over 12 MB	`The photo is larger than 12 MB. Use a smaller photo.`
Not JPEG, PNG or WebP (including HEIC)	`The photo must be a JPEG, PNG or WebP image.`
Both `image_url` and `image_base64`	`Give either image_url or image_base64, not both.`
Broken base64	`image_base64 is not valid base64.`
Not a URL	`image_url is not a valid URL.`
Not http or https	`image_url must be an http or https link.`
Private or local address	`image_url must point to a public website.`
Photo hosted on usemuro.com	`Photos on usemuro.com cannot be fetched from here. Send the photo as image_base64, or link it from another host.`
Host unreachable	`Could not download the photo from <host>. Check that the link is public.`
Host answered with an error	`Downloading the photo failed with HTTP <status>. Check that the link is public.`
More than 3 redirects	`image_url redirects too many times. Link to the image file itself.`

The type is checked from the file’s bytes. HEIC from an iPhone is not accepted by the server: convert it to JPEG first. The CLI does it on macOS. In claude.ai and ChatGPT, pass the photo as a link, not a pasted image.

If you give neither image_url nor image_base64 to visualize_room, it paints Muro’s sample room and says so: Painted on Muro's sample room, because no photo was given. Send image_url or image_base64 to paint your own room.

Colour problems

Checked for free before any credit is spent.

Cause	Message
0 or more than 12 colours	`Give 1 to 12 colours per visualization (got <n>).`
Colour not in the brand	`No colour "<name>" in <brand>. Did you mean: <name (code)>, …?` or `… Use search_paint_colors to find it, or pass its hex.`
Bad hex	`"<value>" is not a hex colour. Use six hex digits like #3D4E57.`
Colour with neither hex nor brand	`Colour <i> needs a hex, or brand and name_or_code.`
Same colour twice	`<hex> is in the list twice. Each colour is charged, so give each one once.`
Unknown brand	`Unknown brand "<input>". Brands in the database: <list>.`
Unknown market	`No market data for "<country>". Markets: US, GB, DE (also AT/CH), PL, FR, ES, IT, NL (also BE/LU), SE, NO, DK, FI. Call without country for every brand.`

Project or job not found

Muro could not find that project or job. It may belong to another account.

Check job_id and project_id from visualize_room, and that you use the same account.

Job still running

Not an error. When colours are not ready after about 45 seconds, visualize_room returns the finished images and this line:

Painted <done> of <total> so far. Call get_visualization with job_id "<job_id>" and project_id "<project_id>" in a few seconds for the rest.

Call get_visualization. Each call waits up to about 25 seconds.

Colours that failed

These colours could not be painted: <list>.
<n> credit(s) were refunded for the failures.

Failed colours are refunded. Under x402, a response with a failed colour is not settled (see below).

Rate limit

HTTP 429 with Retry-After: 60 and a JSON-RPC body:

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32000,
    "message": "Rate limit: 600 requests per minute per client. Retry in 60 seconds."
  }
}

The number is 600 for keyless traffic and 60 for requests with an Authorization header and for OAuth endpoints. See Pricing and limits.

x402 payment

Under x402, a visualize_room or relight_room call without a payment returns isError: true, the requirements in _meta["x402/error"] and this text:

This call costs 0.25 USDC on Base, paid with x402. Pay with an x402-capable client, or use a Muro API key (https://app.usemuro.com/ustawienia) to pay with Muro credits instead.

The amount is the price of that call.

If a payment was sent but not accepted, the text adds the reason, and _meta["x402/error"].error carries it:

This call costs 0.50 USDC on Base, paid with x402. The payment was not accepted (INVALID_PAYMENT). Pay with an x402-capable client, or use a Muro API key (https://app.usemuro.com/ustawienia) to pay with Muro credits instead.

`error` value	Meaning
`PAYMENT_REQUIRED`	No payment on the call. Sign a USDC authorization and call again with `_meta["x402/payment"]`.
`INVALID_PAYMENT`	The payment token could not be decoded, did not match the requirements, or was rejected.
other facilitator reasons	The facilitator’s verification or settlement reason is passed through. `SETTLEMENT_FAILED` means settlement did not complete.

If painting fails, the result ends with You were not charged: the x402 payment was not settled. A payment that is still confirming on-chain does not withhold the images: the result carries _meta["x402/payment-response"] with success: false.

Unreachable or unexpected failures

Cause	Message
Muro API unreachable	`Muro is not reachable right now. Try again in a minute.`
Muro API error	`Muro had a problem with this request. Try again in a minute.`
Muro rejected the request	the reason from Muro, or `Muro rejected the request as invalid.`
Unexpected failure in a paid tool	`Something went wrong while painting. Nothing was charged for work that did not finish. Try again in a minute.`
Colour database error	`The colour database is temporarily unavailable. Try again in a moment.`