API Errors
All API errors follow a consistent shape and use standard HTTP status codes.
Response envelope
json
{
"error": "<error_code>",
"message": "<human-readable message>",
"messages": ["<detail>"]
}The messages array is only present on validation_error (400) responses.
Error code reference
| Status | Code | When |
|---|---|---|
| 400 | validation_error | Invalid request body (details in messages[]) |
| 401 | unauthorized | Missing or invalid API key |
| 404 | not_found | Resource not found or not owned by caller |
| 409 | conflict | Resource state conflict (e.g., deleting a kubbi that is already inactive) |
| 410 | expired | kubbi's TTL has elapsed |
| 410 | gone | kubbi has been burned (max_retrievals reached) or deleted by the producer |
| 429 | rate_limited | Too many requests. Rate limit depends on your plan tier |
| 429 | quota_exceeded | Daily quota, active kubbi limit, or max API keys reached |
| 500 | internal_error | Unexpected server error |
| 501 | not_implemented | API version not available |