API Error Handling
HTTP status codes, error response format, and common error scenarios for the Kubeadapt API. Covers 400, 401, 403, 404, 422, and 500 responses.
All error responses use a consistent JSON format. Check the HTTP status code first, then read the detail field for a description of what went wrong.
Error Response Format
{
"detail": "Error description"
}For validation errors (422), the detail field may be an array of objects describing each invalid field.
Status Codes
| Code | Meaning | When |
|---|---|---|
200 | OK | Request succeeded |
400 | Bad Request | Invalid query parameter, such as an unrecognized timeframe value |
401 | Unauthorized | Missing or invalid API key |
403 | Forbidden | API key lacks the required permission scope, or the requested cluster is not in the key's allowed clusters |
404 | Not Found | Resource does not exist or is not accessible to your organization |
422 | Unprocessable Entity | Request parameter failed validation |
429 | Too Many Requests | Rate limit exceeded for your API key |
500 | Internal Server Error | Unexpected server error |
Common Error Scenarios
400 Bad Request
Returned when a query parameter has an invalid value.
curl -H "Authorization: Bearer ka_your_api_key" \
"https://public-api.kubeadapt.io/v1/clusters/not-a-uuid"{
"detail": "Invalid cluster ID format"
}401 Unauthorized
Returned when the Authorization header is missing or the key is invalid.
curl https://public-api.kubeadapt.io/v1/clusters{
"detail": "API key required. Use 'Authorization: Bearer <api_key>'"
}A valid-looking key that has been revoked or is otherwise invalid returns:
{
"detail": "Invalid API key"
}403 Forbidden
Returned when your key is valid but doesn't have the required scope, when the requested cluster is not in the key's allowed list, or when the key has been revoked.
{
"detail": "Missing required permission: recommendations:read"
}{
"detail": "Access to this cluster is not allowed"
}429 Too Many Requests
Returned when your API key has exceeded the rate limit (100 requests per minute by default). The response includes headers to help you handle the backoff:
{
"detail": "Rate limit exceeded"
}The response also includes:
| Header | Example | Description |
|---|---|---|
X-RateLimit-Limit | 100 | Your limit |
X-RateLimit-Remaining | 0 | Requests left |
X-RateLimit-Reset | 1741910460 | When the window resets (Unix timestamp) |
Retry-After | 42 | Seconds to wait before retrying |
Space your requests evenly rather than sending bursts. If you hit the limit, wait for the Retry-After duration before retrying.
404 Not Found
Returned when the resource ID doesn't exist or belongs to a different organization.
curl -H "Authorization: Bearer ka_your_api_key" \
https://public-api.kubeadapt.io/v1/clusters/cls-nonexistent{
"detail": "Cluster not found"
}Related
- Authentication - API key setup and auth error handling
- Permission Scopes - Scope-related 403 errors
- REST API Overview - Base URL and request format