# Troubleshooting

Every error is JSON: `{"error": {"type": "...", "message": "..."}}`. The message says what to fix.

| You see | Why | Fix |
|---|---|---|
| `401 authentication_error` | no `Authorization: Bearer` header, a mistyped key, or a revoked key | check `echo $JERS_API_KEY`; ask the gateway owner for a new key |
| `402 payment_required` | the tenant's credit is used up | the owner adds credit with `credit add`; reads (`/v1/models`, `/v1/usage`) still work |
| `400 Content-Length is not a number` | a broken client or proxy | send a correct `Content-Length` |
| `413` | the body is over 1 MB (16 MB for `/v1/batches` and `/v1/golden`) | send less state; the engine's window is smaller than that anyway |
| `415` | missing `Content-Type: application/json` | add the header (curl needs `-H "Content-Type: application/json"`) |
| `422 ... state must be non-empty text ...` | empty state, or a number | send a string, an object or an array of strings |
| `422 ... questions must be a nonempty mapping` | `questions` missing or empty | at least one question |
| `422 ... type must be choice, score, or noul` | a typo in `type` | one of the three |
| `422 ... choice needs 1 to 255 named candidates` | `criteria` missing, empty or too big | a map of option name to description |
| `422 ... score needs 2 to 10 ordered levels` | `criteria` is not a list of 2 to 10 | a list, low to high |
| `422 ... a noul's criteria is an object with a true and a false description` | a noul's `criteria` has other keys | `{"true": ..., "false": ...}`, or leave it out |
| `422 this request needs N engine questions; the limit per request is 400` | too many questions, option orders or large choices in one request | split the request, or ask fewer orders |
| `422 ... instructions are required` | no `instructions` | add the question text (a string, object or array) |
| `422 unknown model ...` | a model name Jers does not have | the message lists the names; `jers-latest` always works |
| `422 subject must be ...` | a subject id with spaces, slashes or over 36 characters | letters, digits, underscore, hyphen |
| `422 memory.top_k must be ...` or `memory.min_share ...` | `top_k` not a whole number 1 to 20, `min_share` not 0.05 to 1 | fix the number |
| `422 derive: ...`, or from `POST /v1/memory/rules` `422 the name ... is not allowed` or `... is not allowed in a condition` | an expression uses a name or function that is not allowed | comparisons, arithmetic, `and`/`or`/`not` and the listed functions only (Request options) |
| `422 robust.orders must be a whole number from 1 to 5`, `robust must be true or an object ...`, `windows must be true or an object ...`, `windows.combine maps question ids to one of max, mean, min` | a malformed `robust` or `windows` | see Request options |
| `422 values is an object of at most 50 fields` | `values` is not an object, or too big | send only the fields `derive` and rules use |
| `422 a memory line is at most 2000 characters; ...` | one line of `remember` is too long; nothing was stored | split it into facts, one per line |
| `422 a rule's text is non-empty and at most 500 characters` | an empty or long rule text | one short sentence of what to do |
| `422 text must not be empty` or `concept must not be empty` | `remember` without text, or `forget` without a concept | send the text or the concept |
| `422 context is built by Jers ...` | the request sent `context` | send `subject`, `derive` and `values`; Jers builds the context |
| `403 signup_disabled` or `invite_required` | self-serve sign-up is off, or needs a code | ask the gateway owner |
| `404 no such decision and question` | a `decision_id` from another tenant, a typo, or older than 30 days | feedback within 30 days, with the id the decision returned |
| `409 conflict` | a limit: 5,000 golden cases, a subject's 10,000 memory lines (`subject '...' holds N lines ...; nothing was stored`) or `at most 100 rules per subject` | delete cases, forget lines, or delete rules first |
| `422 invalid JSON ...` or `duplicate JSON key` | malformed body, or the same key twice | validate the JSON; JSON with duplicate keys is rejected on purpose |
| `429 rate_limit_error` with `Retry-After` | over the key's requests per minute, or `too many sign-ups from this address today` | wait the seconds given; the SDKs retry by themselves |
| `502 engine_error` | the engine or the product behind the gateway is down or answered an error | check `GET /health`; nothing was charged |
| `500 server_error` | the gateway failed; the message names only the error type (`request failed: ...`) and the gateway writes no log | tell the gateway owner the time and the request; nothing was charged |

## The answer is not what you expected

- **A choice picks the least bad option.** Add `other` or `none_of_these`. Overlapping descriptions split the probability; make options exclusive.
- **A score sits in the middle for everything.** Levels written as degree words ("moderate", "severe") do not separate; write each level as a situation ("a workaround exists", "no workaround"). A score over a whole document is blunt; ask per-claim Nouls instead.
- **A noul is near 0.5.** The engine cannot tell from the state. Add the fact that decides it to the state, or to the subject's memory, and ask a narrower question.
- **The memory did not change anything.** Check `memory.lines_used` and `memory.lines_seen`. Zero used means recall found no line sharing words with the state: put the subject's name and your states' vocabulary in the lines. Fewer seen than used means the lines and the state together are longer than the engine reads; `lines_dropped` counts lines that did not fit in its 64 context lines. Use `compare: true` to see the two answers side by side, and `placebo: true` to see whether a change came from what the lines say.
- **A rule in memory is ignored or backfires.** The engine does not compare numbers or read negation: "never 17" makes 17 more likely, "stop below 30" is answered by its words. Leave options that must never be chosen out of the question, write what to do, and put conditions in a rule with `when` so they are checked in code (Rules in memory). The `warnings` say when a line has this problem.
- **The answer ignores the end of a long state.** The engine read only the start: `usage.state_truncated` is true and there is a `state_cut` warning. Send the part that matters first, or `"windows": true`.
- **A large choice picks strangely.** Above 20 options the answer comes from two rounds (`rounds: 2`), in groups that follow the order you wrote, and `"robust": true` does not apply; a hierarchy of smaller choices is usually clearer. Up to 20 options, if the answer changes when you reorder them, use `"robust": true`.
- **Every request is slow.** The engine loads its three checkpoints when it starts (`load_seconds` in the engine's `/health`); only a tenant's fine-tuned checkpoint loads on its first request. After that requests take tens of milliseconds; `usage.engine_ms` says where the time goes.
- **Tokens are missing from usage.** They appear only when the engine counts them; characters are always counted and are what input would be priced on if it were not free.