Docs menu

Reference

Errors and limits

Understand Kinro MCP HTTP responses, tool errors, rate limits and retry guidance when integrating business insurance conversations and quotes.

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, including input validation refusals before a tool runs. 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.

Regular connection setup and tool discovery do not consume tool-call capacity. They have a separate, larger capacity of their own, so a client that reconnects in a tight loop can also get 429. Tool calls, including update checks, remain subject to endpoint capacity, as do large or invalid messages. Honor Retry-After whenever a request returns 429.

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.
Input too complexThe arguments contain too many fields or array entries. Nothing was sent.Remove unrelated fields and follow the current tool schema, then retry the corrected call.
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.
Turn failedLeo could not answer the message.Check with get_kinro_messages, then ask the user whether to send it again. Do not resend automatically.
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 processed. Do not repeat a call automatically unless it returned HTTP 429 or 503, or explicitly refused the arguments before processing. Correct refused arguments before trying again.
  • 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.