Skip to content
Get API key

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": {
"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"
}
}
FieldTypeDescription
error.typestringBroad error category: invalid_request_error, authentication_error, billing_error, rate_limit_error, or api_error.
error.codestringMachine-readable error code for programmatic branching (see table below).
error.messagestringHuman-readable explanation naming the limit or parameter. Never contains request content.
error.paramstring (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.

Statuserror.typeerror.codeparamDescription & resolution
400invalid_request_errorinvalid_calibration_profilecalibrationThe calibration token is malformed, truncated, tampered with, or signed with a retired key. Fit a new profile with POST /v1/calibrations.
400invalid_request_errorimages_not_supportedimagesThe request uses an assets map, videos, or a multipart/form-data upload. Send images in the JSON body as base64 data URLs in images.
400invalid_request_errorinvalid_compressed_bodycontent-encodingThe body is not valid data for its Content-Encoding.
401authentication_errormissing_api_key—Missing Authorization: Bearer sk_mouse_... header.
401authentication_errorinvalid_api_key—Key does not start with sk_mouse_, fails its CRC32 checksum, is expired, or has been revoked.
402billing_errorinsufficient_creditsauthorizationPrepaid credit balance is $0.00. Top up or enable auto-reload at /console/billing.
403permission_errorplayground_key_not_allowedauthorizationA 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.
404invalid_request_errormodel_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.
404invalid_request_errortuning_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.
404invalid_request_errornot_found—No such route. Check the path against the API reference.
405invalid_request_errormethod_not_allowed—The route exists but not for this HTTP method; the Allow header lists the ones it accepts.
409invalid_request_errorprofile_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.
409invalid_request_errortune_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.
413invalid_request_errorrequest_too_largebodyRequest body exceeds 4,000,000 bytes (4 MB), before or after decompression.
415invalid_request_errorunsupported_content_encodingcontent-encodingContent-Encoding is not gzip, x-gzip, or zstd.
422invalid_request_errorinvalid_imageimages.<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.
422invalid_request_errortoo_many_imagesimagesMore than 8 images in one request.
422invalid_request_errorinvalid_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).
422invalid_request_errorstate_too_longstatestate exceeds 16,384 tokens. Nothing is truncated or billed; trim state to the fields relevant to your questions.
422invalid_request_errortoo_many_questionsquestionsMore than 128 questions in a single request.
422invalid_request_errortoo_many_optionsquestions.<id>.criteriaA question has more than 255 options.
422invalid_request_errorquestion_too_longquestionsOne 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.
422invalid_request_errortoo_much_workquestionsstate 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.
422invalid_request_errortoo_much_workexamplesOn 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.
422invalid_request_errortoo_few_examplesexamplesFewer 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.
422invalid_request_errortoo_many_examplesexamplesMore than 400 examples sent to POST /v1/calibrations; or on POST /v1/tunings, more than the method allows (5,000 readout, 20,000 LoRA).
422invalid_request_errorinvalid_labellabelsA 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.
422invalid_request_errortoo_many_storedstoreThe account already has 100,000 unexpired stored decisions. Tune on them, wait for them to expire, or DELETE /v1/outcomes.
400invalid_request_errorstorage_disabledstore / outcomesDecision storage is not enabled on this deployment.
404invalid_request_errordecision_not_founddecision_idNo stored decision with that id on this account: it was sent without store, expired after 30 days, or was deleted.
422invalid_request_errortoo_few_examples_per_questionexamplesNo question signature in POST /v1/calibrations had at least 50 labeled examples.
429rate_limit_errorrate_limited—Exceeded the per-key request rate limit (10 RPS, burst 20). Includes Retry-After.
429rate_limit_errorauth_rate_limited—Too many requests with invalid keys from one client in a minute. Includes Retry-After.
429rate_limit_errorwork_rate_limited—The account is over 300,000 tokens of model work per minute (state tokens × questions, across all its keys). Includes Retry-After.
429rate_limit_errortoken_rate_limited—Exceeded the per-key input token rate limit (1,000,000 TPM). Includes Retry-After.
503api_errorengine_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.

When calling POST /v1/decisions on a user-facing or hot agent path:

  1. Do not retry 400, 401, 402, 404, 409, 413, or 422: These are deterministic client errors; fix the request or fall back to baseline harness logic immediately.
  2. Honor Retry-After on 429 and 503: Both 429 Too Many Requests and 503 Service Unavailable include a Retry-After header (in integer seconds). On background or batch paths, retry with exponential backoff + jitter after Retry-After.
  3. 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 ms to 3,000 ms) with 0 or 1 retry 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();
}