Kinro
Docs menu

Reference

Errors and limits

HTTP responses, tool errors, rate limits and how to retry safely.

View as Markdown

Kinro reports problems in two places: HTTP status codes from the endpoint, before any tool runs, and tool results with isError: true, after a tool has run. In both cases the text says what happened and what to do next.

HTTP responses

StatusMeaningWhat to do
200The JSON-RPC message was handled. Check the result for tool errors.—
400The body is not valid JSON, or it is a JSON-RPC batch. Batches are not supported.Send one JSON-RPC message per HTTP request.
403The request came from a web page in a browser. Browser origins are not supported.Call the endpoint from your server or MCP client, not from page scripts.
405The method was not POST. The server offers no event stream to GET.Use POST.
413The request body is larger than 30 MB.Send fewer or smaller inline files per message.
429Kinro's MCP endpoint is at capacity.Wait for the number of seconds in the Retry-After header, then retry.
503Kinro's MCP endpoint is temporarily unavailable. No tool ran.Retry after a short wait.

A 429 or 503 means the request was not processed, so retrying it is safe.

Tool errors

SituationWhat the result saysWhat to do
Empty polling callask_kinro requires a non-empty message.Use get_kinro_messages with wait: true to check for replies. Refresh your client’s tool list and schemas if it still offers empty ask_kinro polling.
No conversationThere is no conversation with Kinro yet.Call ask_kinro with the user's message and no conversation_id, then reuse the ID it returns.
Still answeringLeo is still answering the previous message.Call get_kinro_messages with wait: true to get the reply before sending another message.
Completion unknownLeo's response could not be retrieved, and Kinro cannot confirm whether the message was handled.Do not resend automatically. Check with get_kinro_messages, then ask the user.
Document refusedWhy a file was refused: type, size, encoding, source, or a daily limit. Nothing was sent.Tell the user. Resend without the file if they want to continue. See Documents.
PausedKinro's connection for this app is paused, and the message was not sent.Tell the user to try again later or contact Kinro at kinro.com.
Check failedNew messages could not be retrieved.Check again shortly.

Retrying safely

  • ask_kinro sends its message each time it is called. Never retry it automatically, except after an HTTP 429 or 503, which means nothing was sent.
  • get_kinro_messages sends nothing and is safe to call again. A message is marked new only once, so keep calls sequential and save their results; a message lost on the way stays readable, no longer marked new. See Getting Kinro's messages.
  • When Kinro says it is still working on your message, the message was received. Call get_kinro_messages with wait: true; do not resend.