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. |
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. |
422 Unprocessable Entity | Invalid arguments for the tool. | Check the tool’s input schema from discovery. |
429 Too Many Requests | Per-key rate limit exceeded. | Back off and retry. |
5xx | Server-side error. | Retry with backoff. |
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"
}
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
Handle 401, 404, and 429 before parsing the body.
Check for a status marker
If the body has status: "error" or status: "no_data", handle it explicitly.
Otherwise, use the data
A body with no error or no-data marker is a successful data result.
