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.
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 status | Code | When | Action |
|---|
401 | UNAUTHORIZED | No credential, or one that is malformed, revoked, expired or from an account that cannot connect | Recreate the key or reconnect the app. The WWW-Authenticate header points to the OAuth metadata. |
403 | FORBIDDEN_ORIGIN | The request carries a browser Origin from another site | Call from an MCP client, not from a web page |
405 | none | An authenticated method other than POST | Use POST; the response carries Allow: POST |
413 | REQUEST_TOO_LARGE | The body exceeds 64 KiB | Upload images separately and send their references |
429 | RATE_LIMITED | More than 60 requests a minute on this credential | Wait for the Retry-After header (60 seconds) |
503 | INTERNAL_ERROR | OAuth token verification is temporarily unavailable | Retry after the Retry-After header (5 seconds) |
Authentication and access
| Code | Meaning | Action |
|---|
UNAUTHORIZED | The credential is missing, invalid, revoked or from an account that cannot render | Recreate the key or reconnect the app |
ANONYMOUS_NOT_ALLOWED | A guest account tried to render through a connector | Sign in with a full account |
ACCOUNT_DELETED | The account is being deleted or has been | No action; the account no longer renders |
FORBIDDEN | The account has no access to this resource | Check ownership |
FORBIDDEN_SOURCE | The 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 MB | Upload the file again, within the format and size limits, and use the new reference |
| Code | Meaning | Action |
|---|
INVALID_ARGUMENTS | A 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_REQUEST | The request as a whole is not valid, for example a tool that cannot work on the given image | Check the description, the image references and the chosen tool |
PROMPT_TOO_LONG | The final prompt, built from the description plus the tool's own instructions, passed 16,000 characters while the render was being planned | Shorten the description |
DUPLICATE_REFERENCE | The same image was given as both image and styleReference | Send it once, in the role that matters |
Images and uploads
| Code | Meaning | Action |
|---|
INVALID_IMAGE_URL | Not a public HTTPS image address | Use a publicly reachable URL |
PUBLIC_SOURCE_URL_REQUIRED | The image address is not reachable from the render service | Host it somewhere public |
INVALID_IMAGE | The file cannot be read as a supported image | Convert it to PNG, JPEG or WebP |
INVALID_SOURCE_IMAGE | The stored source is unreadable | Upload it again |
INVALID_MIME | The media type is not accepted | Use a supported format |
INVALID_PREFIX | The upload target is not one the account may write to | Use the key returned by prepare |
IMAGE_TOO_LARGE | The image exceeds the size limit for its path | Reduce it |
TOO_LARGE | The file is empty or over the upload limit | Check the file |
IMAGE_DOWNLOAD_TIMEOUT | The source did not respond in time | Retry, or host the image again |
IMAGE_DOWNLOAD_FAILED | The source could not be fetched | Check the address is still live |
UPLOAD_FAILED | The confirmation did not match the upload | Resend with the same key and staging key |
PRESIGN_DISABLED | Direct upload is temporarily unavailable | Retry later, or send a from_url |
QUOTA_EXCEEDED | Upload allowance is exhausted or blocked | Free space or wait |
NOT_FOUND | The upload, render or project does not exist for this account | Check the id belongs to the account |
Credits
| Code | Meaning | Action |
|---|
INSUFFICIENT_CREDITS | The balance does not cover the batch | The result carries required and balance, and a link to the credit explanation |
QUOTE_CHANGED | The quoted total no longer matches the computed one | Resubmit and accept the new quote |
| Code | Meaning | Action |
|---|
MASK_REQUIRED | The tool needs a marked area, which a connector cannot paint | Use the website |
INVALID_MASK | The marked area is not usable | Use the website and redraw the mark |
UNSUPPORTED_TOOL | The tool is not offered over MCP: upscaling, sketch-to-plan, layout editing, video | Use the website, or choose another tool |
COUNT_CONFIRMATION_REQUIRED | The planner proposed a different image count | Confirm and resubmit |
State, idempotency and service
| Code | Meaning | Action |
|---|
IDEMPOTENCY_CONFLICT | The same requestId was used with different inputs | Use a new requestId for a new request |
SOURCE_CHANGED | The source image changed while the render was being prepared | Retry with the same requestId and unchanged inputs |
SOURCE_FREEZE_CONFLICT | Two preparations raced for the same source | Retry with the same requestId |
SOURCE_NOT_PREPARED | The source is not ready yet | Retry shortly |
PLAN_EXPIRED | The prepared plan is older than 30 minutes | Start a new request with a new requestId |
PLAN_NOT_READY, PLANNING_STATE_CHANGED, STALE_PLAN | The plan moved on while the call was in flight | Query the render, or start a new request |
RESULT_EXPIRED | The result is no longer available | Re-render |
PROVIDER_DISABLED | Rendering is temporarily paused | Retry later with the same requestId |
WORKFLOW_START_FAILED | The render did not start | Query the render, or retry with the same requestId |
SUBMISSION_UNKNOWN | The provider's answer was not received | Keep querying; do not submit a replacement render |
INTERNAL_ERROR | A server-side failure | Retry with the same requestId and inputs |
RATE_LIMITED | A rate limit was reached; see Limits for which | The 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
| Limit | Value | Counted per |
|---|
| Requests | 60 per minute | Credential: each API key or connected app |
| Renders started | 10 per minute | Account, across all credentials |
Uploads (prepare and from_url) | 15 per minute | Account, shared with uploads from the website |
| Render plans | 30 per hour | Account, shared with the website |
| Request body | 64 KiB | Request |
| Unsubmitted plan validity | 30 minutes | Plan |
| Images per render | 4 | Render |
| Description length | 16,000 characters | Render |
| Active API keys | 5 | Account |
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