# 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 $JEPELA_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 Jepela does not have | the message lists the names; `jepela-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 method is auto (the default), engine or match`, or `method match answers choice questions only` | a misspelt `method`, or `match` on a request with only scores and yes/no questions | see 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 Jepela ...` | the request sent `context` | send `subject`, `derive` and `values`; Jepela 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 |
| `409` from `POST /v1/finetune` | another of your fine-tuning jobs is running, or `the engine is off; it has to be on to train` | wait for the job (`GET /v1/finetune`), or try again later |
| `422 you have N labelled cases ...; fine-tuning needs at least 20 ...` | too few golden cases with expected answers | add cases with `POST /v1/golden` |
| `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` with `the engine is off` | the GPU engine is switched off | try again later; the SDKs retry with backoff; nothing was charged |
| `502 engine_error` | the engine or the memory service 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, the subject's names or the question: put the subject's name and your states' vocabulary in the lines, add the names the subject goes by with `POST /v1/memory/aliases`, or pin a line that must always count. 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, `explain: true` to see how far each line moved them, 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. Remove options that must never be chosen in code (an exclusion rule, or leave them 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 is matched by default (`"method": "match"` in the answer): give each option a short description of what it means, since an option without one is matched by its name alone. With `"method": "engine"` it 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`.
- **A request takes longer than usual.** 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.
- **The memory changed an answer it should not have.** Lines are recalled by shared words, so a line about another topic can come along. Try `"memory": {"focus": true}`, which keeps only lines that share a word with the state beyond the subject's name, or raise `min_share`.