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 |
428 | Precondition Required | Tool requires credentials not yet configured |
429 | Too Many Requests | Rate limit exceeded |
500 | Internal Server Error | Something went wrong on our end |
502 | Bad Gateway | Tool execution failed in the sandbox |
504 | Gateway Timeout | Tool execution timed out (30-second limit) |
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 |
|---|
"Tool requires credentials not yet configured" | Tool needs API keys you haven't provided (428) | Set credentials in the dashboard or via the Environment Variables API |
"Insufficient token balance" | Not enough tokens to execute the tool (402) | Add tokens to your wallet |
"Tool execution failed" | The tool's code threw an error (502) | Contact the tool seller - this is a seller-side issue |
"Tool execution timed out" | Tool didn't complete within 30 seconds (504) | Contact the tool seller - the tool may need optimization |
"Tool has not passed validation" | Tool artifact hasn't been validated yet (400) | Wait for validation to complete, or contact the seller |
| Error | Cause | Fix |
|---|
"Rate limit exceeded" | Too many requests in the time window | Wait and retry, or reduce request frequency |