Errors & Status

Nikiwa signals outcomes at two levels: standard HTTP status codes for transport and auth, and in-body status markers for tool-level results.

HTTP status codes

Status	Meaning	What to do
`200 OK`	Request handled. Check the body for a tool-level status marker.	Read the body.
`400 Bad Request`	The server could not read or parse the request body.	Check the request body and encoding. Malformed JSON normally returns `422`.
`401 Unauthorized`	Missing, malformed, or revoked key.	Check the `Authorization` header; rotate the key if revoked.
`404 Not Found`	The tool name is unknown or not public.	Verify the name against discovery.
`409 Conflict`	`DUPLICATE_REQUEST`: the `Idempotency-Key` was already used. `PRICE_CHANGED`: prices changed since the version you sent.	See Credit errors.
`422 Unprocessable Entity`	Invalid arguments, malformed JSON, or a body that is not a JSON object.	Check the tool’s input schema from discovery.
`429 Too Many Requests`	Per-key rate limit exceeded, or not enough credits.	Inspect `detail` and follow the handling below.
`503 Service Unavailable`	`CREDITS_UNAVAILABLE`: credits could not be checked, so the call did not run.	Retry after `Retry-After` seconds.
`5xx`	Server-side error. When the tool itself fails, the call’s credits are refunded. A gateway timeout can arrive after the tool already finished, in which case the call is charged.	Retry with backoff. A retry with the same `Idempotency-Key` returns `409 DUPLICATE_REQUEST` if the first call completed.

HTTP error bodies

HTTP errors use a detail field. Each tool page includes these responses in its response selector.

{
  "detail": "There was an error parsing the body"
}

{
  "detail": "Invalid API key"
}

{
  "detail": "Unknown tool 'unknown_tool'"
}

{
  "detail": "Invalid arguments for 'get_wallet_token_holdings'."
}

{
  "detail": "Rate limit exceeded"
}

{
  "detail": {
    "error_code": "PLAN_LIMIT_REACHED",
    "meter": "credits",
    "plan_id": "plus",
    "limit": 600,
    "resets_at": "2026-10-14T09:30:00+00:00",
    "balance": 3,
    "required": 8,
    "message": "Not enough credits for this request (needs 8, 3 left). Upgrade your plan or wait for your credits to refresh."
  }
}

The plan, balance, and reset time above are illustrative. See Credit errors for all credit responses. Request validation errors use an array in detail. For example, a body containing only { returns:

{
  "detail": [
    {
      "type": "json_invalid",
      "loc": ["body", 1],
      "msg": "JSON decode error",
      "input": {},
      "ctx": {
        "error": "Expecting property name enclosed in double quotes"
      }
    }
  ]
}

loc identifies the invalid input; msg and type describe the failure. Other validation errors can include different input and ctx values.

Credit errors

Tools API and MCP calls are paid with credits. A call refused for credits is not charged and does not run. Credit errors put an object in detail with an error_code and a message.

`error_code`	Status	Meaning	What to do
`PLAN_LIMIT_REACHED`	`429`	The account’s credit balance cannot cover this call. `balance` is what is left, `required` is the tool’s price.	Wait until `resets_at`, or upgrade the plan. Immediate retries fail the same way.
`DUPLICATE_REQUEST`	`409`	The `Idempotency-Key` belongs to a request that already completed or is still running.	Do not retry with the same key. Use a new key for a new call.
`PRICE_CHANGED`	`409`	You sent `X-Credit-Catalog-Version` and prices have changed since that version.	Read the new prices in `credit_catalog`, then send again with the new `catalog_version`.
`CREDITS_UNAVAILABLE`	`503`	Credits could not be checked, so the call did not run. `retryable` is `true`.	Retry after `Retry-After` seconds, with the same `Idempotency-Key` if you sent one.

{
  "detail": {
    "error_code": "PLAN_LIMIT_REACHED",
    "meter": "credits",
    "plan_id": "plus",
    "limit": 600,
    "resets_at": "2026-10-14T09:30:00+00:00",
    "balance": 3,
    "required": 8,
    "message": "Not enough credits for this request (needs 8, 3 left). Upgrade your plan or wait for your credits to refresh."
  }
}

{
  "detail": {
    "error_code": "DUPLICATE_REQUEST",
    "meter": "credits",
    "plan_id": null,
    "limit": null,
    "resets_at": null,
    "message": "This request was already received."
  }
}

{
  "detail": {
    "error_code": "PRICE_CHANGED",
    "meter": "credits",
    "plan_id": null,
    "limit": null,
    "resets_at": null,
    "catalog_version": "2026-10-v1",
    "credit_catalog": {
      "version": "2026-10-v1",
      "chat": { "fast": 4, "thinking": 25, "investigation": 40, "nikiwa_pro_fast": 5, "nikiwa_pro_thinking": 92, "module_refresh": 4 },
      "tools": { "get_wallet_pnl": 25, "resolve_name": 1 },
      "default_tool_weight": 8
    },
    "message": "Credit prices changed. Check the new prices and send again."
  }
}

{
  "detail": {
    "error_code": "CREDITS_UNAVAILABLE",
    "meter": "credits",
    "plan_id": null,
    "limit": null,
    "resets_at": null,
    "retryable": true,
    "message": "Credits are temporarily unavailable. Please try again."
  }
}

The values above are illustrative, and the PRICE_CHANGED example shows only part of credit_catalog.

Headers

Retry-After on a PLAN_LIMIT_REACHED response gives the seconds until credits refresh. It is omitted when the refresh date is not known yet, for example while a failed renewal payment is pending.
Retry-After: 1 is sent with CREDITS_UNAVAILABLE.
The per-key rate limiter’s 429 does not send Retry-After.
Successful responses do not include balance headers. Check your balance in the app; see Credits.

On MCP

The MCP server returns credit errors as a tool result rather than a protocol error. The result has status: "error", a message, and the same error_code and fields as above:

{
  "status": "error",
  "message": "Not enough credits for this request (needs 8, 3 left). Upgrade your plan or wait for your credits to refresh.",
  "error_code": "PLAN_LIMIT_REACHED",
  "meter": "credits",
  "plan_id": "plus",
  "limit": 600,
  "resets_at": "2026-10-14T09:30:00+00:00",
  "balance": 3,
  "required": 8
}

Tool-level status markers

A tool call can return 200 OK and still contain no data. Nikiwa tools return their data object on success, or one of these markers:

{
  "...": "the tool's structured data"
}

{
  "status": "no_data"
}

{
  "status": "error",
  "message": "Human-readable explanation"
}

Always branch on the body, not just the HTTP code. A 200 with {"status": "no_data"} means the query was valid but nothing matched, for example a wallet with no activity on the requested network.

Recommended handling

Check the HTTP status

For non-200 responses, read detail. Correct 400, 401, 404, and 422 failures before retrying. For 429, distinguish the request-rate limit from PLAN_LIMIT_REACHED. For 409 and 503, check detail.error_code.

Check for a status marker

If the body has status: "error", status: "no_data", or an error field, handle it explicitly.

Otherwise, use the data

A body with no error or no-data marker is a successful data result.

​HTTP status codes

​HTTP error bodies

​Credit errors

​Headers

​On MCP

​Tool-level status markers

​Recommended handling

HTTP status codes

HTTP error bodies

Credit errors

Headers

On MCP

Tool-level status markers

Recommended handling