Errors

Errors use the OpenAI-compatible shape {"error": {"code": "..."}}; branch on code. A 400 on the bearer path also carries message (the rule that was broken) and type: invalid_request_error. The table below lists every code the edge answers, generated from the code that answers it.

JSON

{"error": {"code": "invalid-research-request",
           "message": "max_tokens: 1..32768",
           "type": "invalid_request_error"}}

HTTP	code	When	What to do
400	`invalid-json`	The body is not JSON, or empty.	Send content-type: application/json and valid JSON.
400	`invalid-research-request`	The request does not fit the admission shape. On the bearer path error.message names the rule (for example "max_tokens: 1..32768").	Read message and fix it; drop unknown parameters.
400	`inference-rejected`	The origin refused this request itself (context window, shape, or max_tokens spent before any content: "output-budget-exhausted"). error.message carries the reason.	For a thinking model send reasoning {"enabled": false} or raise max_tokens (64 is not enough for a title).
400	`invalid-job-id`	The idempotency-key (or jobId) on /v1/research/jobs is not a v4 UUID.	Use a UUID v4.
400	`invalid-application`	The researcher application body is malformed.	Provide verificationMode, consent, purpose and scope.
400	`invalid-ekyc-request`	The verification start body is malformed (scopeId / tasks).	Start it from the account console.
401	`sign-in-required`	No cookie session and no valid PAT.	Send Authorization: Bearer kc_pat_….
401	`token-revoked`	A revoked (or never registered) token.	Issue a new token in the account console.
403	`origin-not-allowed`	A browser POST from a foreign origin. A curl with neither Origin nor Bearer currently lands here too.	Call from a mithril.fund page, or send Authorization: Bearer kc_pat_… (the agent path).
403	`research-access-denied`	The PAT failed verification, or the authority refused with 403 for a reason other than the ones below.	Check the token; read /v1/research/status.
403	`verification-required`	Identity verification (card) missing or expired (red team only).	Complete verification in the account console.
403	`verification-expired`	Verification is older than 365 days.	Re-verify.
403	`trust-route-required`	No current trust route.	Restart verification; a retry a few seconds later can also clear it.
403	`screening-expired`	AML/CTF screening older than 24 hours.	Wait for re-review.
403	`review-required`	Under review, or additional checks are needed.	Follow the account console.
403	`policy-acceptance-required`	The policy version changed; re-acceptance is required.	Accept it in the account console.
403	`session-reverification-required`	The continuous-session evidence is stale.	Reload the page, or retry with the PAT.
403	`identity-mismatch`	The record's principal does not match.	Contact support@kotoba.cloud.
403	`research-scope-required`	The task is not covered by an approved scope.	code-review is approved with verification; apply for others.
403	`model-route-not-configured`	A listed model whose route is not configured; no quota is spent.	Use a model whose availability is served in /v1/models.
403	`guardrail-blocked`	Content policy (CSAM, CBRN, fraud-as-a-service): a separate screening model judged the request's user turns. Recorded as a durable receipt.	Do not resend. A false positive: send the request id to support@kotoba.cloud.
403	`firewall-denied`	That task kind is closed at your assurance rung.	Use the three standard tasks, or raise the rung.
403	`job-reverification-required`	The ladder re-verification failed while polling a job.	Read /v1/research/status for the reason.
403	`prepaid-card-not-accepted`	A prepaid / virtual card in verification.	Use a credit or debit card.
403	`token-scope-insufficient`	This personal API token lacks the scope this route needs; the message names the required scope and the token's own.	Issue a token with that scope at /account.
404	`job-not-found`	No job with that id (including another principal's).	Use the id from creation.
405	`method-not-allowed`	Wrong method for the route. /v1/messages, /v1/responses and the Gemini wire land here too (not served).	Use the OpenAI chat.completions wire.
402	`insufficient-balance`	A paying account's prepaid AI credit is insufficient (the message states the balance and the hold this request needed, in dollars) and the free quota is used up too.	Add credit at admin.mithril.fund/billing/ (paid requests are not counted against the free quota).
409	`idempotency-conflict`	The same job id with different input.	New input, new id.
413	`body-too-large`	The body exceeds 2 MiB.	Keep input within 524,288 characters.
415	`json-required`	content-type is not application/json.	Send the header.
429	`free-quota-exhausted`	The free 1,000/day allowance is used up (resets at UTC midnight, no Retry-After). With a balance the request runs paid instead.	Retry the next UTC day, or add credits.
429	`upstream-rate-limited`	The route's provider for this model is rate-limited upstream (the provider, not the key or the quota). error.message carries the provider's words. A paid hold is released.	Retry shortly, or use another model from /v1/models.
502	`inference-failed`	The inference run failed (upstream refusal or error). A paid hold is released.	Resend; if it persists, the status page and support.
502	`invalid-inference-receipt`	The job succeeded without text or tool calls.	Resend.
502	`invalid-job-receipt`	The authority's answer is not in the contract shape.	Resend; if it persists, support.
503	`guardrail-unavailable`	The content-screening model did not answer (route not configured, timeout, unreadable answer). Nothing was judged; no job was created.	Retry; the reason is in the message's parentheses.
503	`research-service-unavailable`	The authority is unreachable, or an unnamed failure.	Wait and resend.
503	`verification-provider-not-configured`	No research authority in this environment.	Use production api.mithril.fund.
503	`pat-not-configured`	No PAT signing key in this environment.	Use production api.mithril.fund.
503	`card-verification-not-configured`	The card side of verification is temporarily unavailable.	Retry later.
504	`inference-timeout`	The server-side wait (14 minutes) elapsed; the job continues.	Resend the identical request to re-attach to the same job.

Guardrail and firewall 403s are recorded as durable receipts. The 429 resets at UTC midnight without Retry-After. A paid answer may carry settlement: "pending" instead of an error (see Per-request cost).