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.
{"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 |
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. | Call from a kotoba.cloud page, or use a PAT. |
| 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). Recorded as a durable receipt. | Do not resend. |
| 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. |
| 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. |
| 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. |
| 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 |
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.kotoba.cloud. |
| 503 |
pat-not-configured
|
No PAT signing key in this environment. | Use production api.kotoba.cloud. |
| 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).