Reference
Error Codes
HTTP error codes and error messages returned by the Kate API.
| Code | Name | Description |
|---|
200 | OK | Request succeeded |
201 | Created | Resource created successfully |
202 | Accepted | Async task started - poll for results |
400 | Bad Request | Invalid parameters or request body |
401 | Unauthorized | Missing or invalid API key / JWT token |
402 | Payment Required | Insufficient token balance |
403 | Forbidden | You don't have permission to access this resource |
404 | Not Found | Resource doesn't exist |
409 | Conflict | Resource already exists (e.g., duplicate subscription, existing draft) |
422 | Unprocessable Entity | Request is well-formed but contains semantic errors |
429 | Too Many Requests | Rate limit exceeded |
500 | Internal Server Error | Something went wrong on our end |
All errors return JSON with a detail field:
{
"detail": "Artifact not found"
}
Some errors include additional context:
{
"detail": "Insufficient token balance. Required: 500, available: 120"
}
| Error | Cause | Fix |
|---|
"Invalid API key" | API key is incorrect or revoked | Generate a new key in the dashboard |
"Missing authorization header" | No x-api-key or Authorization header | Include your API key in the request |
"Token expired" | JWT token has expired | Re-authenticate to get a new token |
| Error | Cause | Fix |
|---|
"Artifact not found" | Invalid artifact ID or not owned by you | Check the artifact ID |
"Artifact already has a draft" | Tried to extract when draft exists | Delete the existing draft or publish it |
"Cover not generated" | Tried to publish without a cover | Generate the cover first, or publish (which auto-generates) |
"File too large" | Upload exceeds 20 MB | Reduce file size |
| Error | Cause | Fix |
|---|
"Already subscribed" | Agent already has an active subscription | No action needed - query the artifact |
"Insufficient token balance" | Not enough tokens for subscription | Add tokens to your wallet |
"Artifact not listed" | Artifact is not published | Contact the seller or wait for publishing |
| Error | Cause | Fix |
|---|
"No active subscription" | Agent isn't subscribed to this artifact | Subscribe first |
"Insufficient token balance" | Not enough tokens for per-query charge | Add tokens |
| Error | Cause | Fix |
|---|
"Run is not in RUNNING status" | Tried to upload spans to a completed run | Create a new run |
"Run not found" | Invalid run ID | Check the run ID |
| Error | Cause | Fix |
|---|
"Rate limit exceeded" | Too many requests in the time window | Wait and retry, or reduce request frequency |