{
  "schema": "niua.errors/v1",
  "page": "https://ohao.tech/niua/docs/errors",
  "envelope": "Every error NIUA raises is { \"error\": { \"code\", \"message\", \"doc_url\" } }; match on code, never on message. A few framework rejections before NIUA sees the request (malformed JSON, a bad UUID in the path) are plain text with no envelope. doc_url is https://ohao.tech/niua/docs/errors#<code with - for _>.",
  "errors": [
    {
      "code": "invalid_api_key",
      "status": [
        401
      ],
      "means": "The call had no API key, a wrong one or a revoked one, so NIUA could not tell who is calling.",
      "next": "Sign in at https://ohao.tech/niua/login, create a key at https://ohao.tech/niua/console/keys and send it as Authorization: Bearer niua_live_...; checks are free.",
      "try": [
        "export NIUA_API_KEY=niua_live_...   # from https://ohao.tech/niua/console/keys",
        "curl -H \"Authorization: Bearer $NIUA_API_KEY\" https://api.ohao.tech/api/v1/contracts   # 200 means the key works",
        "curl -X POST \"https://api.ohao.tech/api/v1/playground/samples/prop-lamp/check?contract=glb.prop@1&variant=fixed\"   # no key needed"
      ]
    },
    {
      "code": "act_as_unknown_user",
      "status": [
        401
      ],
      "means": "The MCP server signed you in, but that email has no NIUA account yet.",
      "next": "Create the account at https://ohao.tech/niua/login with the same email, then call the tool again."
    },
    {
      "code": "invalid_admin_token",
      "status": [
        401
      ],
      "means": "Reserved and not currently returned: it was for admin-only routes, which no longer exist on this API.",
      "next": "Use the public /api/v1 routes in https://api.ohao.tech/openapi.yaml."
    },
    {
      "code": "permission_denied",
      "status": [
        403
      ],
      "means": "The key is valid but does not cover this call: a read-scope key on a write route, an API key trying to manage keys, someone other than the owner simulating a checked file, or publishing to the public showcase, which is staff only.",
      "next": "Use a full-scope key for writes, simulate only files you checked yourself, and manage keys and spend limits in the console in a browser."
    },
    {
      "code": "insufficient_funds",
      "status": [
        402
      ],
      "means": "The wallet cannot cover this paid generation call, and nothing was charged.",
      "next": "Add funds at https://ohao.tech/niua/console/billing, or stick to checks, which are always free."
    },
    {
      "code": "spend_limit_exceeded",
      "status": [
        402
      ],
      "means": "The call would pass the spend limit on this API key; the body carries limit_cents, spent_cents, period and price_cents.",
      "next": "Do not retry; ask the key's owner to raise or clear the limit in the console."
    },
    {
      "code": "quota_exceeded",
      "status": [
        402,
        429
      ],
      "means": "You hit a per-user limit: 429 when calls come too fast, 402 when your 5 GB of upload storage is full.",
      "next": "On 429 wait the seconds in the Retry-After header and retry; on 402 delete old uploads to free space."
    },
    {
      "code": "unknown_model",
      "status": [
        400
      ],
      "means": "The model field names a model that is not in the catalog; the body lists valid_models.",
      "next": "Pick a model from valid_models or from GET https://api.ohao.tech/api/v1/models and send the call again."
    },
    {
      "code": "invalid_request",
      "status": [
        400
      ],
      "means": "The body or a parameter is malformed or out of range, and the message names what is wrong.",
      "next": "Fix what the message names, checking the call against https://api.ohao.tech/openapi.yaml, and send it again."
    },
    {
      "code": "idempotency_key_in_use",
      "status": [
        409
      ],
      "means": "A project with that name, or a board session with that id, already exists.",
      "next": "Pick a different project name or session id and send the call again."
    },
    {
      "code": "conflict",
      "status": [
        409
      ],
      "means": "What you are creating already exists, for example a saved contract with the same id@version.",
      "next": "Bump version, or pick a new id, and save again."
    },
    {
      "code": "not_found",
      "status": [
        404
      ],
      "means": "Nothing your account can see exists at that path or id; receipts from the no-account playground are never stored, so they are not found here either.",
      "next": "Check the id; to check a receipt you hold, POST it to https://api.ohao.tech/api/v1/receipts/verify as {\"receipt\": ...}."
    },
    {
      "code": "region_restricted",
      "status": [
        451
      ],
      "means": "The model's license does not allow use from your region (mesh-decompose excludes the EU, UK and South Korea), and nothing was charged.",
      "next": "Use another model, or call from a region the license allows."
    },
    {
      "code": "service_unavailable",
      "status": [
        503
      ],
      "means": "A part NIUA needs for this call is down or switched off on this server, such as hosted generation.",
      "next": "Retry after a short wait; if it keeps failing, the feature is off on this server."
    },
    {
      "code": "upstream_unavailable",
      "status": [
        503
      ],
      "means": "Reserved and not currently returned: it is for a provider NIUA depends on that does not answer.",
      "next": "Retry after a short wait."
    },
    {
      "code": "generation_failed",
      "status": [
        200
      ],
      "means": "A paid generation ran and failed; it comes back as HTTP 200 with status failed, and the wallet is refunded.",
      "next": "Read the error field of GET /api/v1/jobs/{id}, adjust the input and try again."
    },
    {
      "code": "internal",
      "status": [
        500
      ],
      "means": "Something broke inside NIUA, not in your request.",
      "next": "Retry once; if it repeats, send the x-request-id response header to Ohao through https://ohao.tech/contact."
    }
  ]
}