API Reference
API Errors
When an API request fails, Keep'em returns a consistent error response with an HTTP status code, error code, and human-readable message.
Error Response Format
{
"error": {
"code": "resource_not_found",
"message": "Event not found",
"status": 404
}
}Common Error Codes
| Status | Code | Description |
|---|---|---|
| 400 | invalid_request | Missing or invalid parameters |
| 401 | unauthorized | Invalid or missing API key |
| 403 | forbidden | Valid key but insufficient permissions |
| 402 | usage_limit_exceeded | Plan limit reached (Stream Units or AI Messages) |
| 404 | resource_not_found | Requested resource doesn't exist |
| 429 | rate_limited | Too many requests |
| 500 | internal_error | Something went wrong on our end |
Rate Limiting
When rate-limited, the response includes headers indicating when you can retry:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705348800Usage Limit Errors (402)
A 402 response means the project has exceeded its plan limits. The response includes details:
{
"error": {
"code": "usage_limit_exceeded",
"message": "AI message limit reached",
"details": {
"metric": "ai_messages",
"current": 200,
"limit": 200,
"allowOverage": false
}
}
}If allowOverage is true, requests succeed and overages are billed. If false, the request is denied.