Errors
Errors use standard HTTP status codes and a JSON body that says what went wrong.
Base URLhttps://api.kalle.build/v1AuthBearer kalle_sk_…VersionKalle-Version: 2026-11-01
Error shape
Error response
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "max_tokens: must be at least 1"
},
"request_id": "req_7f3KxQ2m"
}Every response has a request-id header. Include it when you contact support.
Error types
| Status | Type | What to do |
|---|---|---|
| 400 | invalid_request_error | Fix the request. The message says which field. |
| 401 | authentication_error | Check the key and the Authorization header. |
| 403 | permission_error | The key lacks the scope, or the balance is empty. |
| 404 | not_found_error | Check the ID or the model name. |
| 409 | conflict_error | The resource changed. Fetch it again and retry. |
| 413 | request_too_large | Send less, or upload files first. |
| 429 | rate_limit_error | Wait for retry-after seconds, then retry. |
| 500 | api_error | Retry with backoff. |
| 529 | overloaded_error | Retry with backoff, or use another model. |
Retrying
Retry 429, 500 and 529 with exponential backoff, starting at one second. The SDKs do this for you. Send an Idempotency-Key header on POST requests so a retry never creates something twice.