Vue d’ensemble

Errors and limits

Stable error codes from the MCP server and the limits that cause them, with the action to take next.

Open .md

An error from a tool arrives as a tool result with isError set, an error code, a human-readable message and a nextStep. The code is the stable part; the message is written for the person reading it and can change.

Errors before a tool runs

Some requests are refused at the HTTP level, before any JSON-RPC handling. These come back as an HTTP status with a JSON body of code, message and nextStep, not as a tool result.

HTTP statusCodeWhenAction
401UNAUTHORIZEDNo credential, or one that is malformed, revoked, expired or from an account that cannot connectRecreate the key or reconnect the app. The WWW-Authenticate header points to the OAuth metadata.
403FORBIDDEN_ORIGINThe request carries a browser Origin from another siteCall from an MCP client, not from a web page
405noneAn authenticated method other than POSTUse POST; the response carries Allow: POST
413REQUEST_TOO_LARGEThe body exceeds 64 KiBUpload images separately and send their references
429RATE_LIMITEDMore than 60 requests a minute on this credentialWait for the Retry-After header (60 seconds)
503INTERNAL_ERROROAuth token verification is temporarily unavailableRetry after the Retry-After header (5 seconds)

Authentication and access

CodeMeaningAction
UNAUTHORIZEDThe credential is missing, invalid, revoked or from an account that cannot renderRecreate the key or reconnect the app
ANONYMOUS_NOT_ALLOWEDA guest account tried to render through a connectorSign in with a full account
ACCOUNT_DELETEDThe account is being deleted or has beenNo action; the account no longer renders
FORBIDDENThe account has no access to this resourceCheck ownership
FORBIDDEN_SOURCEThe image cannot be used by this account: it belongs to another account, no longer exists (an upload past its seven days, a deleted result), is not an image, or exceeds 32 MBUpload the file again, within the format and size limits, and use the new reference

Inputs

CodeMeaningAction
INVALID_ARGUMENTSA field is missing, has the wrong type or length, or is unknown. Over MCP this includes a prompt that is empty or longer than 16,000 characters.Fix the call; unknown fields are rejected rather than ignored
INVALID_REQUESTThe request as a whole is not valid, for example a tool that cannot work on the given imageCheck the description, the image references and the chosen tool
PROMPT_TOO_LONGThe final prompt, built from the description plus the tool's own instructions, passed 16,000 characters while the render was being plannedShorten the description
DUPLICATE_REFERENCEThe same image was given as both image and styleReferenceSend it once, in the role that matters

Images and uploads

CodeMeaningAction
INVALID_IMAGE_URLNot a public HTTPS image addressUse a publicly reachable URL
PUBLIC_SOURCE_URL_REQUIREDThe image address is not reachable from the render serviceHost it somewhere public
INVALID_IMAGEThe file cannot be read as a supported imageConvert it to PNG, JPEG or WebP
INVALID_SOURCE_IMAGEThe stored source is unreadableUpload it again
INVALID_MIMEThe media type is not acceptedUse a supported format
INVALID_PREFIXThe upload target is not one the account may write toUse the key returned by prepare
IMAGE_TOO_LARGEThe image exceeds the size limit for its pathReduce it
TOO_LARGEThe file is empty or over the upload limitCheck the file
IMAGE_DOWNLOAD_TIMEOUTThe source did not respond in timeRetry, or host the image again
IMAGE_DOWNLOAD_FAILEDThe source could not be fetchedCheck the address is still live
UPLOAD_FAILEDThe confirmation did not match the uploadResend with the same key and staging key
PRESIGN_DISABLEDDirect upload is temporarily unavailableRetry later, or send a from_url
QUOTA_EXCEEDEDUpload allowance is exhausted or blockedFree space or wait
NOT_FOUNDThe upload, render or project does not exist for this accountCheck the id belongs to the account

Credits

CodeMeaningAction
INSUFFICIENT_CREDITSThe balance does not cover the batchThe result carries required and balance, and a link to the credit explanation
QUOTE_CHANGEDThe quoted total no longer matches the computed oneResubmit and accept the new quote

Tools and masks

CodeMeaningAction
MASK_REQUIREDThe tool needs a marked area, which a connector cannot paintUse the website
INVALID_MASKThe marked area is not usableUse the website and redraw the mark
UNSUPPORTED_TOOLThe tool is not offered over MCP: upscaling, sketch-to-plan, layout editing, videoUse the website, or choose another tool
COUNT_CONFIRMATION_REQUIREDThe planner proposed a different image countConfirm and resubmit

State, idempotency and service

CodeMeaningAction
IDEMPOTENCY_CONFLICTThe same requestId was used with different inputsUse a new requestId for a new request
SOURCE_CHANGEDThe source image changed while the render was being preparedRetry with the same requestId and unchanged inputs
SOURCE_FREEZE_CONFLICTTwo preparations raced for the same sourceRetry with the same requestId
SOURCE_NOT_PREPAREDThe source is not ready yetRetry shortly
PLAN_EXPIREDThe prepared plan is older than 30 minutesStart a new request with a new requestId
PLAN_NOT_READY, PLANNING_STATE_CHANGED, STALE_PLANThe plan moved on while the call was in flightQuery the render, or start a new request
RESULT_EXPIREDThe result is no longer availableRe-render
PROVIDER_DISABLEDRendering is temporarily pausedRetry later with the same requestId
WORKFLOW_START_FAILEDThe render did not startQuery the render, or retry with the same requestId
SUBMISSION_UNKNOWNThe provider's answer was not receivedKeep querying; do not submit a replacement render
INTERNAL_ERRORA server-side failureRetry with the same requestId and inputs
RATE_LIMITEDA rate limit was reached; see Limits for whichThe result carries retryAfterSeconds: 60. A minute is enough for the per-minute limits; the hourly plan cap can take longer, so wait and retry with the same requestId rather than looping.

Codes not listed here

The server can return a code that is not on this page, for example one passed through from the rendering provider. Such a code comes with a generic message and a nextStep. Treat the code as an identifier for support, follow nextStep, and when a renderId exists, query get_render before retrying. Never answer an unfamiliar code by creating a replacement render with a new requestId; that risks paying twice for the same work.

Limits

LimitValueCounted per
Requests60 per minuteCredential: each API key or connected app
Renders started10 per minuteAccount, across all credentials
Uploads (prepare and from_url)15 per minuteAccount, shared with uploads from the website
Render plans30 per hourAccount, shared with the website
Request body64 KiBRequest
Unsubmitted plan validity30 minutesPlan
Images per render4Render
Description length16,000 charactersRender
Active API keys5Account

A render that fails does not consume its credits, and a request that is refused for any reason above is never partly submitted.

MCP tools · Credits and plans · MCP quickstart