Reference
Errors
Failure modes across transport, auth, input validation, and runtime — with recovery paths.
Transport errors
| Code | Status | Description | Recovery |
|---|---|---|---|
| 307_redirect | 307 | Request hit /mcp without trailing slash. | Always call /mcp/ — many Streamable HTTP clients drop the connection on the redirect. |
| 400_https_required | 400 | Production environment received a non-HTTPS request. | Set ENVIRONMENT=production only behind an HTTPS proxy; otherwise unset ENFORCE_HTTPS. |
| spawn_enoent | — | Inspector configured as STDIO with an HTTP URL as command. | Switch transport to Streamable HTTP. Use the URL field, not Command. |
Authentication
| Code | Status | Description | Recovery |
|---|---|---|---|
| missing_bearer | 401 | Authorization header missing or malformed. | Include `Authorization: Bearer <jwt>` on every request. |
| invalid_audience | 401 | Token `aud` != wmstudio-mcp. | Re-mint via /oauth/token or `create_test_token()` in development. |
| revoked_token | 401 | Token present in Redis `mcp:tokens:revoked`. | Restart the OAuth flow. |
| bad_oauth_state | — | Supabase rejected a stale or duplicated state parameter. | Most often a redirect_to misconfiguration — check the runbook in `oauth-fly-supabase-runbook.md`. |
Input validation
| Code | Status | Description | Recovery |
|---|---|---|---|
| missing_required | 400 | Required parameter not supplied (e.g. `prompt` or `reference_image_url`). | Check the tool's `Parameters` table; required params are tagged. |
| invalid_image | 400 | Image URL is unreachable, not an image, or larger than 12MB. | Re-host on a public CDN; PNG/JPG/WebP only; max 12MB. |
| unsupported_model | 400 | Model id not enabled on this deployment. | See `/docs/configuration#models` for the live catalogue. |
| consent_required | 403 | Likeness or Digital Twin call missing `consent_acknowledged: true`. | Surface a consent UI in your client and set the flag explicitly. |
Runtime
| Code | Status | Description | Recovery |
|---|---|---|---|
| insufficient_credits | 402 | User has insufficient WM Studio credits for the requested job. | Direct user to /dashboard/credits to top up. |
| rate_limited | 429 | Per-user or per-tool rate window exceeded. | Respect the `Retry-After` header; back off exponentially. |
| provider_unavailable | 503 | Upstream model provider is temporarily down (fal.ai, OpenAI, etc.). | Retry after 30–60s. The provider is reported in the error body. |
| job_timeout | — | Async job did not finish within its TTL (default 10 min). | Retry with a smaller batch or simpler prompt. |
| job_failed | — | Provider returned a render failure. | Inspect `error.message` for the provider's reason. |
By tool
Each tool documents its own error shapes — click through for the full table.
Tool-specific error tables are added as edge cases are catalogued.