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, or a request with the same Idempotency-Key is still running. 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. |
| 501 | not_implemented_error | The endpoint is documented but not available yet. See availability. |
| 529 | overloaded_error | Retry with backoff, or use another model. |
Retrying
Retry 429, 500 and 529 with exponential backoff, starting at one second.
Send an Idempotency-Key header on POST requests so a retry never runs twice. Within 24 hours, the same key gets the first response back with idempotent-replayed: true; the same key with a different body is a 400. Streamed replies and 5xx errors are not stored, so they can be retried with the same key.