[{"data":1,"prerenderedAt":15},["ShallowReactive",2],{"doc-errors":3},{"blocks":4,"markdown":14},[5,8,12],{"kind":6,"html":7},"html","\u003Cp>Two rules make the rest of this page readable.\u003C\u002Fp>\n\u003Cp>\u003Cstrong>Every error carries a code.\u003C\u002Fstrong> The HTTP status says what kind of problem it is;\nthe code says which one. Branch on the code — statuses are shared, codes are not.\u003C\u002Fp>\n",{"kind":9,"lang":10,"code":11},"code","json","{\n  \"error\": \"QUOTA_EXCEEDED\",\n  \"detail\": \"this organisation does not have enough credits for that call\",\n  \"context\": { \"balance\": \"0\", \"needed\": \"1\", \"limit\": \"20\", \"used\": \"20\", \"plan\": \"free\" },\n  \"request_id\": \"01J…\"\n}",{"kind":6,"html":13},"\u003Cdiv class=\"doc-table\">\n\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Field\u003C\u002Fth>\n\u003Cth>Meaning\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\n\u003Ctr>\n\u003Ctd>\u003Ccode class=\"chip chip--error\">error\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The code. Stable — safe to branch on\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>detail\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Plain language. \u003Cstrong>Not\u003C\u002Fstrong> stable; do not match on it\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>context\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Whatever is useful for this code. Shape varies\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>request_id\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Quote this when you ask us about a call\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\n\u003C\u002Ftable>\n\u003C\u002Fdiv>\n\u003Cp>\u003Cstrong>A refusal is not an error.\u003C\u002Fstrong> An oracle that ran and refused answers\n\u003Ccode>200\u003C\u002Fcode> with \u003Ccode>"status": "invalid"\u003C\u002Fcode>. See \u003Ca href=\"\u002Fverdicts\">Verdicts\u003C\u002Fa>.\u003C\u002Fp>\n\u003Ch2 id=\"codes\">Codes\u003C\u002Fh2>\n\u003Cdiv class=\"doc-table\">\n\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Status\u003C\u002Fth>\n\u003Cth>Code\u003C\u002Fth>\n\u003Cth>Meaning\u003C\u002Fth>\n\u003Cth>Retry?\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\n\u003Ctr>\n\u003Ctd>401\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>KEY_MISSING\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>No bearer token was sent\u003C\u002Ftd>\n\u003Ctd>After fixing the header\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>401\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>KEY_UNKNOWN\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The token is not recognised\u003C\u002Ftd>\n\u003Ctd>No — check for a truncated paste\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>401\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>KEY_REVOKED\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The key was revoked\u003C\u002Ftd>\n\u003Ctd>Never. Mint a new one\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>401\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>KEY_EXPIRED\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The key passed its expiry\u003C\u002Ftd>\n\u003Ctd>Never. Mint a new one\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>403\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>ORG_DISABLED\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The key is fine; its organisation is not active\u003C\u002Ftd>\n\u003Ctd>No. Keep the key and contact support\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>400\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>SIGNATURE_INVALID\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>A figure token is malformed, altered or expired\u003C\u002Ftd>\n\u003Ctd>No — draw from a fresh answer\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>402\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>QUOTA_EXCEEDED\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The allowance is spent\u003C\u002Ftd>\n\u003Ctd>When the window turns, or on a bigger plan\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>404\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>NOT_FOUND\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>No such oracle, or no organisation for this key\u003C\u002Ftd>\n\u003Ctd>No — read \u003Ccode>GET \u002Fv1\u002Foracles\u003C\u002Fcode>\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>422\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>VALIDATION_FAILED\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The request is malformed, or the format is one this oracle cannot produce\u003C\u002Ftd>\n\u003Ctd>After correcting it. \u003Ccode>context.available\u003C\u002Fcode> lists the formats\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>422\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>DATA_REQUIRED\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>A chart request does not give the values to draw\u003C\u002Ftd>\n\u003Ctd>After putting them in the intent, or with \u003Ccode>allow_generated_data\u003C\u002Fcode>\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>500\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>INTERNAL\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Something failed that we did not anticipate\u003C\u002Ftd>\n\u003Ctd>Yes, once. Then send us the \u003Ccode>request_id\u003C\u002Fcode>\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>501\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>UNSUPPORTED\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Nothing draws this figure's target\u003C\u002Ftd>\n\u003Ctd>No\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>503\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>UPSTREAM_UNAVAILABLE\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>A service the call depends on is briefly unavailable\u003C\u002Ftd>\n\u003Ctd>Yes, after a short wait\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>200\u003C\u002Ftd>\n\u003Ctd>—\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>"status": "error"\u003C\u002Fcode> — our fault\u003C\u002Ftd>\n\u003Ctd>Yes. Nothing was billed\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\n\u003C\u002Ftable>\n\u003C\u002Fdiv>\n\u003Cp>That is the whole list. A request that fails validation names the field in\n\u003Ccode>context.parameter\u003C\u002Fcode>. Each endpoint's page lists exactly which of these it can\nreturn.\u003C\u002Fp>\n\u003Ch2 id=\"the-distinctions-worth-honouring\">The distinctions worth honouring\u003C\u002Fh2>\n\u003Cp>\u003Cstrong>\u003Ccode>402\u003C\u002Fcode> is not \u003Ccode>401\u003C\u002Fcode>.\u003C\u002Fstrong> Your credential is fine; the allowance is spent. A client\nthat treats a spent quota as an auth failure re-prompts for a key that was never\nthe problem — often to a human, in the middle of the night.\u003C\u002Fp>\n\u003Cp>\u003Cstrong>\u003Ccode>ORG_DISABLED\u003C\u002Fcode> is \u003Ccode>403\u003C\u002Fcode>, not \u003Ccode>401\u003C\u002Fcode>.\u003C\u002Fstrong> The key is fine; the organisation behind\nit is not active. A client that throws the key away and asks for a new one gets\nthe same answer with the new one. Keep it, and tell a person.\u003C\u002Fp>\n\u003Cp>\u003Cstrong>\u003Ccode>KEY_REVOKED\u003C\u002Fcode> and \u003Ccode>KEY_EXPIRED\u003C\u002Fcode> are permanent.\u003C\u002Fstrong> No amount of backoff will\nhelp. A client that retries these forever is a client that never tells anyone it\nis broken.\u003C\u002Fp>\n\u003Cp>\u003Cstrong>A \u003Ccode>200\u003C\u002Fcode> can still be a failure.\u003C\u002Fstrong> \u003Ccode>"status": "error"\u003C\u002Fcode> is ours, and unbilled.\nBranch on \u003Ccode>status\u003C\u002Fcode>, not only on the status line.\u003C\u002Fp>\n\u003Cp>See \u003Ca href=\"\u002Fhandling-verdicts\">Handle every verdict\u003C\u002Fa> for the client code.\u003C\u002Fp>\n","# Errors\n\n> Every code you can receive, what it means, and whether retrying helps.\n\nTwo rules make the rest of this page readable.\n\n**Every error carries a code.** The HTTP status says what kind of problem it is;\nthe code says which one. Branch on the code — statuses are shared, codes are not.\n\n```json\n{\n  \"error\": \"QUOTA_EXCEEDED\",\n  \"detail\": \"this organisation does not have enough credits for that call\",\n  \"context\": { \"balance\": \"0\", \"needed\": \"1\", \"limit\": \"20\", \"used\": \"20\", \"plan\": \"free\" },\n  \"request_id\": \"01J…\"\n}\n```\n\n| Field | Meaning |\n|---|---|\n| `error` | The code. Stable — safe to branch on |\n| `detail` | Plain language. **Not** stable; do not match on it |\n| `context` | Whatever is useful for this code. Shape varies |\n| `request_id` | Quote this when you ask us about a call |\n\n**A refusal is not an error.** An oracle that ran and refused answers\n`200` with `\"status\": \"invalid\"`. See [Verdicts](https:\u002F\u002Fdocs.formalogic.io\u002Fverdicts).\n\n## Codes\n\n| Status | Code | Meaning | Retry? |\n|---|---|---|---|\n| 401 | `KEY_MISSING` | No bearer token was sent | After fixing the header |\n| 401 | `KEY_UNKNOWN` | The token is not recognised | No — check for a truncated paste |\n| 401 | `KEY_REVOKED` | The key was revoked | Never. Mint a new one |\n| 401 | `KEY_EXPIRED` | The key passed its expiry | Never. Mint a new one |\n| 403 | `ORG_DISABLED` | The key is fine; its organisation is not active | No. Keep the key and contact support |\n| 400 | `SIGNATURE_INVALID` | A figure token is malformed, altered or expired | No — draw from a fresh answer |\n| 402 | `QUOTA_EXCEEDED` | The allowance is spent | When the window turns, or on a bigger plan |\n| 404 | `NOT_FOUND` | No such oracle, or no organisation for this key | No — read `GET \u002Fv1\u002Foracles` |\n| 422 | `VALIDATION_FAILED` | The request is malformed, or the format is one this oracle cannot produce | After correcting it. `context.available` lists the formats |\n| 422 | `DATA_REQUIRED` | A chart request does not give the values to draw | After putting them in the intent, or with `allow_generated_data` |\n| 500 | `INTERNAL` | Something failed that we did not anticipate | Yes, once. Then send us the `request_id` |\n| 501 | `UNSUPPORTED` | Nothing draws this figure's target | No |\n| 503 | `UPSTREAM_UNAVAILABLE` | A service the call depends on is briefly unavailable | Yes, after a short wait |\n| 200 | — | `\"status\": \"error\"` — our fault | Yes. Nothing was billed |\n\nThat is the whole list. A request that fails validation names the field in\n`context.parameter`. Each endpoint's page lists exactly which of these it can\nreturn.\n\n## The distinctions worth honouring\n\n**`402` is not `401`.** Your credential is fine; the allowance is spent. A client\nthat treats a spent quota as an auth failure re-prompts for a key that was never\nthe problem — often to a human, in the middle of the night.\n\n**`ORG_DISABLED` is `403`, not `401`.** The key is fine; the organisation behind\nit is not active. A client that throws the key away and asks for a new one gets\nthe same answer with the new one. Keep it, and tell a person.\n\n**`KEY_REVOKED` and `KEY_EXPIRED` are permanent.** No amount of backoff will\nhelp. A client that retries these forever is a client that never tells anyone it\nis broken.\n\n**A `200` can still be a failure.** `\"status\": \"error\"` is ours, and unbilled.\nBranch on `status`, not only on the status line.\n\nSee [Handle every verdict](https:\u002F\u002Fdocs.formalogic.io\u002Fhandling-verdicts) for the client code.\n",1793819973842]