Fehler und Rate Limits | kanman Dokumentation

Diese Seite beschreibt, was die programmatischen Schnittstellen von kanman zurückgeben, wenn etwas schiefgeht: die REST-API und der MCP-Server von kanman. Tool-Fehler des MCP-Servers stehen unter MCP-Tools. Wie kanman Webhook-Zustellungen wiederholt, beschreiben die Zustellregeln.

Fehler der REST-API

Jeder Fehler hat dieselbe Form:

{ "error": { "code": "not_found", "message": "Run run-7f3k does not exist in this workspace." } }

code ist stabil und für Ihren Code gedacht; message ist für Menschen gedacht und kann sich ändern.

Status	`code`	Wann
`400`	`invalid_request`	Ein Parameter oder der Body ist ungültig, zum Beispiel ein unbekannter Filterwert, ein fehlerhafter `cursor` oder eine Option, die nicht zur Entscheidung gehört.
`401`	`unauthorized`	Das Token fehlt, ist unbekannt, widerrufen oder abgelaufen, sein Workspace wurde gelöscht, oder die Person, der es gehört, hat den Workspace verlassen. Die Antwort trägt `WWW-Authenticate: Bearer`.
`403`	`forbidden`	Dem Token fehlt die Berechtigung des Endpunkts, oder das Audit-Log wurde mit dem Token einer Person angefragt, die weder Owner noch Admin ist.
`404`	`not_found`	Der Endpunkt oder das Objekt existiert im Workspace des Tokens nicht.
`405`	`method_not_allowed`	Den Pfad gibt es, aber nicht mit dieser Methode.
`409`	`conflict`	Die Entscheidung ist schon beantwortet.
`410`	`gone`	Ein entfernter Endpunkt der ersten API-Version (Projekte und Aufgaben).
`429`	`rate_limited`	Zu viele Anfragen. Siehe Rate Limits.
`500`	`internal_error`	Bei kanman ist etwas schiefgegangen. Versuchen Sie es erneut.

Fehler des MCP-Servers

Der MCP-Server antwortet in JSON-RPC 2.0. Eine Anfrage, die er nicht annehmen kann, bekommt ein Fehlerobjekt:

{ "jsonrpc": "2.0", "id": null, "error": { "code": -32600, "message": "Unauthorized" } }

Ein Tool, das scheitert, liefert keinen Protokollfehler. Es liefert ein normales Tool-Ergebnis mit isError: true und einer lesbaren Meldung, damit der Coding-Agent darauf reagieren kann.

HTTP-Statuscodes

Status	Wann
`200`	Die Anfrage wurde bearbeitet. Auch Tool-Fehler kommen mit `200`.
`202`	Eine Benachrichtigung wurde angenommen.
`400`	Der Body ist kein gültiges JSON.
`401`	Das Token fehlt, ist unbekannt, widerrufen oder abgelaufen, oder die Story in der Adresse gehört nicht zum Workspace des Tokens. Die Antwort trägt `WWW-Authenticate: Bearer`.
`405`	Die Methode ist nicht `POST`. Der Server ist zustandslos und bietet keinen Event-Stream.
`413`	Der Body ist größer als 256 KB.
`500`	Bei kanman ist etwas schiefgegangen. Versuchen Sie es erneut.

Fehlercodes

Code	Meldung	Bedeutung
`-32700`	Parse error	Der Body ist kein gültiges JSON.
`-32600`	Unauthorized, Request too large, Invalid JSON-RPC message	Die Anfrage wurde abgewiesen, bevor sie bearbeitet wurde. Senden Sie eine JSON-RPC-Nachricht pro Anfrage; Batches werden nicht angenommen.
`-32601`	Method not found	Der Server kennt die JSON-RPC-Methode nicht.
`-32602`	Unknown tool	`tools/call` nennt ein Tool, das der Server nicht hat.
`-32603`	Internal error	Bei kanman ist etwas schiefgegangen.

Rate Limits

Die REST-API erlaubt 120 Anfragen pro Minute und Token. Das Zeitfenster beginnt zur vollen Minute. Jede Antwort enthält:

Header	Bedeutung
`X-RateLimit-Limit`	Erlaubte Anfragen pro Minute.
`X-RateLimit-Remaining`	Verbleibende Anfragen in der laufenden Minute.
`X-RateLimit-Reset`	Unix-Zeit in Sekunden, zu der die nächste Minute beginnt.

Über dem Limit antwortet die API mit 429 und Retry-After in Sekunden. Für den MCP-Server veröffentlicht kanman keine Anfragelimits; Coding-Agenten rufen ihn wenige Male pro Story auf, weit unter jeder Grenze, die Sie bemerken würden.

Wiederholen

Wiederholen Sie 500-Antworten und Netzwerkfehler nach einer kurzen Pause, mit wachsenden Abständen.
Warten Sie nach einem 429 so viele Sekunden, wie Retry-After angibt.
Wiederholen Sie 400, 401, 403, 404, 409 und 410 nicht: Ändern Sie zuerst die Anfrage oder das Token.
Tool-Ergebnisse mit isError: true sind Antworten, keine Ausfälle. Lesen Sie die Meldung: Sie sagt dem Agenten, was als Nächstes zu tun ist, zum Beispiel „No run is active for this story yet. Call start_work first.“
Webhook-Zustellungen wiederholt kanman bis zu viermal. Siehe Zustellregeln.

Weniger Anfragen stellen

Abonnieren Sie Webhooks, statt die API nach neuen Runs oder Entscheidungen abzufragen.
Lesen Sie eine lange Historie mit limit 100 und hören Sie auf, wenn nextCursor null ist.
Rufen Sie get_story einmal zu Beginn auf statt vor jedem Schritt.
Senden Sie report_progress, wenn die Phase wechselt, nicht für jede Datei.