Errors
Every non-2xx response from https://api.mouse.dev uses a single JSON error envelope. Error messages name the offending field or limit and never echo your request content (state, instructions, or criteria).
Error envelope
Section titled “Error envelope”{ "error": { "type": "invalid_request_error", "code": "state_too_long", "message": "state is 18,204 tokens; mouse-preview-2026-10-13 reads at most 16,384. Nothing was truncated or billed.", "param": "state" }}| Field | Type | Description |
|---|---|---|
error.type | string | Broad error category: invalid_request_error, authentication_error, billing_error, rate_limit_error, or api_error. |
error.code | string | Machine-readable error code for programmatic branching (see table below). |
error.message | string | Human-readable explanation naming the limit or parameter. Never contains request content. |
error.param | string (optional) | Dotted path of the offending request field (e.g. "state", "questions.intent.criteria", "examples") or header ("authorization"). |
Every error response includes Mouse-Request-Id, Mouse-Region, Mouse-Data-Retention: none, and Cache-Control: no-store. 4xx responses are never billed.
HTTP status codes and error codes
Section titled “HTTP status codes and error codes”| Status | error.type | error.code | param | Description & resolution |
|---|---|---|---|---|
400 | invalid_request_error | invalid_calibration_profile | calibration | The calibration token is malformed, truncated, tampered with, or signed with a retired key. Fit a new profile with POST /v1/calibrations. |
400 | invalid_request_error | images_not_supported | images | The request uses an assets map, videos, or a multipart/form-data upload. Send images in the JSON body as base64 data URLs in images. |
400 | invalid_request_error | invalid_compressed_body | content-encoding | The body is not valid data for its Content-Encoding. |
401 | authentication_error | missing_api_key | — | Missing Authorization: Bearer sk_mouse_... header. |
401 | authentication_error | invalid_api_key | — | Key does not start with sk_mouse_, fails its CRC32 checksum, is expired, or has been revoked. |
402 | billing_error | insufficient_credits | authorization | Prepaid credit balance is $0.00. Top up or enable auto-reload at /console/billing. |
403 | permission_error | playground_key_not_allowed | authorization | A Console Playground key tried to start (not quote) or delete a tuning, store a decision (store: true), or delete stored decisions. Use a standard key or /console/tunings. |
404 | invalid_request_error | model_not_found | — | Unknown model string, or a tuned id or alias (mouse-1:ft-...) that is not on this account, has no ready tuning, or was deleted. Query GET /v1/models for active aliases (mouse-1, mouse), snapshots, and your tunings. |
404 | invalid_request_error | tuning_not_found | — | GET/DELETE /v1/tunings/{id} with an id that is not on this account or was deleted, or a baseline that is not a ready tuning on this account. |
404 | invalid_request_error | not_found | — | No such route. Check the path against the API reference. |
405 | invalid_request_error | method_not_allowed | — | The route exists but not for this HTTP method; the Allow header lists the ones it accepts. |
409 | invalid_request_error | profile_model_mismatch | — | The supplied calibration profile was fitted on a different model snapshot than the one serving this request. Pin the model version or refit the profile. |
409 | invalid_request_error | tune_in_progress | — | A tuning job is already queued or running on this account. GET /v1/tunings shows it; wait for it to finish or delete it. |
413 | invalid_request_error | request_too_large | body | Request body exceeds 4,000,000 bytes (4 MB), before or after decompression. |
415 | invalid_request_error | unsupported_content_encoding | content-encoding | Content-Encoding is not gzip, x-gzip, or zstd. |
422 | invalid_request_error | invalid_image | images.<n> | An image is not a base64 data:image/png, jpeg or webp URL, cannot be decoded, is animated, is over 16 megapixels, or has an aspect ratio over 200:1. Image URLs are never fetched. An image under 65,536 pixels is accepted with a warnings entry instead. See Images. |
422 | invalid_request_error | too_many_images | images | More than 8 images in one request. |
422 | invalid_request_error | invalid_schema | <field.path> | Request body failed schema validation (e.g. missing state or questions, unknown field inside a question, choice criteria passed as an array instead of an object, or invalid calibration label). |
422 | invalid_request_error | state_too_long | state | state exceeds 16,384 tokens. Nothing is truncated or billed; trim state to the fields relevant to your questions. |
422 | invalid_request_error | too_many_questions | questions | More than 128 questions in a single request. |
422 | invalid_request_error | too_many_options | questions.<id>.criteria | A question has more than 255 options. |
422 | invalid_request_error | question_too_long | questions | One question reads more than 18,432 tokens together with the state (its instructions, options and framing). Shorten the question or the state. Nothing is billed. |
422 | invalid_request_error | too_much_work | questions | state tokens × questions exceeds 64,000. The model reads the whole state once per question; send fewer questions per request or a shorter state. Nothing is billed. |
422 | invalid_request_error | too_much_work | examples | On POST /v1/tunings: the examples total over 30M tokens, a LoRA job is over 8M training tokens (both epochs), or the job (fee plus estimated GPU) would cost over $250. Nothing is billed. |
422 | invalid_request_error | too_few_examples | examples | Fewer than 200 examples sent to POST /v1/calibrations, or fewer than the method needs on POST /v1/tunings (200 readout, 1,000 LoRA), including outcomes that match no labelled decision. |
422 | invalid_request_error | too_many_examples | examples | More than 400 examples sent to POST /v1/calibrations; or on POST /v1/tunings, more than the method allows (5,000 readout, 20,000 LoRA). |
422 | invalid_request_error | invalid_label | labels | A label on POST /v1/decisions/{id}/outcome does not fit its question: not true/false for noul, not an option key for choice, not a level index for score, or not a question of that decision. |
422 | invalid_request_error | too_many_stored | store | The account already has 100,000 unexpired stored decisions. Tune on them, wait for them to expire, or DELETE /v1/outcomes. |
400 | invalid_request_error | storage_disabled | store / outcomes | Decision storage is not enabled on this deployment. |
404 | invalid_request_error | decision_not_found | decision_id | No stored decision with that id on this account: it was sent without store, expired after 30 days, or was deleted. |
422 | invalid_request_error | too_few_examples_per_question | examples | No question signature in POST /v1/calibrations had at least 50 labeled examples. |
429 | rate_limit_error | rate_limited | — | Exceeded the per-key request rate limit (10 RPS, burst 20). Includes Retry-After. |
429 | rate_limit_error | auth_rate_limited | — | Too many requests with invalid keys from one client in a minute. Includes Retry-After. |
429 | rate_limit_error | work_rate_limited | — | The account is over 300,000 tokens of model work per minute (state tokens × questions, across all its keys). Includes Retry-After. |
429 | rate_limit_error | token_rate_limited | — | Exceeded the per-key input token rate limit (1,000,000 TPM). Includes Retry-After. |
503 | api_error | engine_timeout | — | The model did not answer within the 30-second engine deadline, usually because it is starting after an idle period (a few minutes). Includes Retry-After: 10. Not billed. |
Handling retries and timeouts
Section titled “Handling retries and timeouts”When calling POST /v1/decisions on a user-facing or hot agent path:
- Do not retry
400,401,402,404,409,413, or422: These are deterministic client errors; fix the request or fall back to baseline harness logic immediately. - Honor
Retry-Afteron429and503: Both429 Too Many Requestsand503 Service Unavailableinclude aRetry-Afterheader (in integer seconds). On background or batch paths, retry with exponential backoff + jitter afterRetry-After. - Bound total latency on critical paths: In interactive agent loops (such as tool-call gating or message routing), set a per-request deadline (e.g.
1,500 msto3,000 ms) with0or1retry and fall back to your deterministic floor if the call times out.
async function decideWithFallback(payload: unknown) { const res = await fetch("https://api.mouse.dev/v1/decisions", { method: "POST", headers: { Authorization: `Bearer ${process.env.MOUSE_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify(payload), signal: AbortSignal.timeout(2_500), });
if (res.status === 429 || res.status === 503) { const retryAfterSec = Number(res.headers.get("retry-after") ?? "1"); await new Promise((r) => setTimeout(r, retryAfterSec * 1_000)); // Optional single retry for background jobs }
if (!res.ok) { const { error } = await res.json(); throw new Error(`[${error.code}] ${error.message}`); } return res.json();}