Error design for MCP image and video tools
Use actionable codes for auth, scopes, credits, rates, uploads, and provider failures.
For an HTTP MCP server, an invalid or expired bearer token fails before the creative tool can run. The current authorization specification requires HTTP 401 for invalid or expired tokens. Insufficient permission is different: runtime scope failure should use HTTP 403 with a Bearer `WWW-Authenticate` challenge that identifies `insufficient_scope`, the minimum scopes required for the operation, and protected-resource metadata. A client can then request the union of its earlier scopes and the newly required set through bounded step-up authorization.
Do not collapse both cases into `generation_failed`. A 401 tells the client to obtain a valid token; a 403 scope challenge tells it which permission is missing. Neither response proves that an image or video job was submitted. Limit reauthorization attempts and preserve no bearer token, authorization code, refresh token, cookie, or PKCE verifier in shared logs.
- 401
- Token missing, invalid, or expiredAcquire or refresh authorization, then retry within a finite attempt limit.
- 403
- Token lacks the required operation scopeRead the Bearer challenge and request the complete required scope set rather than guessing broad permissions.
- Submission state
- Not startedAn authorization rejection at the MCP boundary is not evidence that a provider job or credit charge exists.
Separate protocol failure from a tool that ran and failed
An MCP image or video tool needs two error lanes. Use a JSON-RPC error when the request itself is not a valid tool call: the JSON cannot be parsed, the method or tool is unknown, the parameters do not satisfy the call schema, or the server cannot process the protocol request. Use a normal `tools/call` result with `isError: true` when the handler understood the call but generation could not proceed because an upload was invalid, credits were unavailable, a provider rejected the job, or another business rule failed.
That distinction changes recovery. A model cannot repair malformed JSON by waiting, and it should not answer insufficient credits by resubmitting the same paid operation. The current MCP tools specification says execution errors should contain actionable feedback that clients provide to models for self-correction. For media tools, actionable means naming the failed boundary, stating whether submission occurred, and giving one safe next action without exposing tokens, private upload paths, signed URLs, prompts, or provider internals.
- Protocol lane
- JSON-RPC `error`Reserve it for request structure, unknown operations, protocol-version problems, and server-level protocol failure.
- Execution lane
- `result.isError: true`Use it when the tool ran far enough to classify an input, account, provider, or workflow failure.
- Recovery test
- Can changed arguments or a human decision resolve it?If yes, return the exact correction or escalation; do not hide it behind a generic internal-error message.
Give every execution error a stable, bounded contract
MCP standardizes the result envelope, not a universal vocabulary for creative-service failures. Define application codes such as `upload_type_unsupported`, `insufficient_credits`, or `provider_unavailable` in your own documented result schema rather than presenting them as MCP codes. A useful error variant includes a stable code, a short message, a retry classification, the required user action, safe operation state, and a correlation identifier. Optional fields such as `retryAfterMs`, `jobId`, accepted media types, or maximum upload bytes belong only where the service actually knows them.
Declare the machine-readable result with an `outputSchema`, preferably as a union of success and error variants, and return matching `structuredContent`. The current tools specification requires server-produced structured results to conform when an output schema exists and says clients should validate them. Keep a concise text content block too for compatibility and human display. Do not put stack traces, raw provider bodies, credentials, filesystem paths, or private media URLs in either representation.
- code
- Stable application identifierMachines branch on this value; prose can change without breaking recovery logic.
- operationState
- `rejected`, `accepted`, or `unknown`This tells a client whether a new generation might duplicate work.
- nextAction
- One bounded correctionExamples are reauthorize, upload a supported file, add credits with human approval, poll an existing job, wait, or escalate.
Classify rate, credit, upload, and provider failures differently
HTTP 429 means too many requests in a server-chosen period; RFC 6585 permits `Retry-After` and leaves counting policy to the service. As non-product design guidance, preserve a returned delay, cap retries, and label whether the observed response came from the MCP HTTP boundary or was represented by the tool as a downstream execution error. Do not infer a reset time, quota number, or retry permission unless the current response or primary service documentation supplies it.
The other branches are conditional application-policy examples, not claims about OfflineCreator or any provider. If a service defines a credit failure as requiring human approval, its contract can mark that code non-retryable until an operator changes the account state. If current service documentation defines upload constraints, an error can name the violated rule and only those documented alternatives. If a service can prove whether a provider accepted a request, its error can return that state and a safe job identifier; if it cannot, the contract should disclose that uncertainty and direct the client to a documented reconciliation operation when one exists. Without a documented idempotency or reconciliation contract, this page makes no claim that either resubmission or status lookup is safe.
- Rate limited
- Wait with a capHonor documented delay guidance and stop after the workflow deadline.
- Insufficient credits
- Apply the service's documented budget policyWhere the product requires human approval, stop for that decision; this page does not assert a universal credit workflow.
- Invalid upload
- Use only verified input constraintsRecommend a revision only when current primary documentation establishes the accepted media type, size, or other rule.
- Provider outcome unknown
- Disclose uncertaintyPoint to reconciliation only when the service documents it; do not promise that lookup or resubmission is safe.
Use codes that do not collide with MCP or JSON-RPC
JSON-RPC reserves negative ranges for its standard and server errors. The 2026-07-28 MCP specification further reserves `-32020` through `-32099` for MCP-defined protocol errors and directs new application-defined purposes outside the JSON-RPC reserved range. A creative service should not assign `-32602` to insufficient credits or invent a meaning for an MCP-reserved number. That would make a business decision look like malformed protocol input and encourage the wrong recovery.
The cleaner design is to keep JSON-RPC numbers for protocol failures and place media-specific names in the execution result contract. Version that vocabulary, document whether each code is retryable, and retain an `unknown` fallback for newer codes. A client that does not recognize `provider_policy_rejection` should still be able to display the message, avoid blind retry, and escalate with the safe correlation identifier.
- `-32602`
- Invalid JSON-RPC parametersUse it for malformed call parameters, not account balance, provider policy, or upload storage state.
- `-32020` to `-32099`
- Reserved for MCP specification errorsDo not allocate service-specific generation meanings in this current reserved sub-range.
- Creative error codes
- Application schema stringsKeep them stable and namespaced in documentation without claiming they are protocol-standard.
Choose the next guide from the failed boundary
Use the rate-limit guide when the error is specifically a request or generation throttle and you need a bounded backoff policy. Use the client-configuration guide when the client cannot discover or call tools because its server declaration shape is wrong. Return to the learning center when transport, authorization, tool execution, and asynchronous job state have not yet been separated. The next page should answer the observed boundary, not repeat a generic retry checklist.
Evidence boundary
The evidence ledger limits normative statements to the cited MCP, JSON-RPC, and HTTP claims at the passages where readers encounter them. The proposed application fields, string codes, stopping rules, and review record are explicitly non-product design guidance. They must be replaced or confirmed against current first-party documentation before describing any service's credit, upload, provider, retry, reconciliation, idempotency, cost, or media behavior.
The 2026-08-09 last30days run returned 67 community and grounding items; only two were classified relevant to error contracts, and neither was promoted into the claim ledger as a substitute for primary specification text. Optional X search was not configured, Reddit returned a partial lane after HTTP 429, and Linkup web-fetch was unauthorized during supplementation, so primary pages were rechecked by direct fetch. No authenticated product exercise was performed. These are disclosed methodology limits, not facts attributed to the protocol sources, and this block intentionally carries no external citation.