Errors & Rate Limits
Error responses and rate limiting for Kodey API
Error Responses
Standard Error Format
{
"error": "Error type",
"message": "Human-readable error description"
}
Common Error Codes
| HTTP Status | Error | Description |
|---|---|---|
400 | Bad Request | Invalid request body or missing required fields |
401 | Unauthorized | Invalid or missing API key |
403 | Forbidden | Publishable key used for secret-key-only endpoint |
404 | Not Found | Resource not found |
429 | Too Many Requests | Rate limit exceeded |
500 | Internal Server Error | Server error |
Authentication Errors
Invalid API Key:
{
"message": "Unauthorized: Invalid API key."
}
Publishable Key Access Denied:
{
"error": "Forbidden",
"message": "This endpoint requires a secret API key (sk_live_*). You are using a publishable API key (pk_live_*) which only has access to chat and message endpoints.",
"allowedEndpoints": [
"POST /chat - Create a chat",
"GET /chat/:chatId - Get chat details",
"POST /chat/:chatId/message - Send a message",
"GET /chat/:chatId/message - List messages"
],
"upgradeInstructions": "Publishable API keys are restricted to chat endpoints. Please use your secret API key (sk_live_*) for full API access."
}
Rate Limits
| Key Type | Limit | Window |
|---|---|---|
Publishable (pk_live_) | 100 requests | 1 minute |
Secret (sk_live_) | 1000 requests | 1 minute |
Rate Limit Headers
Rate limit headers are included in all responses:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1705315800
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum requests allowed in the window |
X-RateLimit-Remaining | Requests remaining in current window |
X-RateLimit-Reset | Unix timestamp when the window resets |
Rate Limit Exceeded Response
When you exceed the rate limit, you'll receive a 429 Too Many Requests response:
{
"error": "Too Many Requests",
"message": "Rate limit exceeded. Please retry after 60 seconds.",
"retryAfter": 60
}