Errors
One error envelope for every endpoint, the HTTP statuses it uses, and how the Python client raises them.
Every error, from any endpoint, has the same envelope. type is the broad class, code names the specific problem, param points at the offending field when there is one, and details carries structured extras such as the validation errors or the quota that was hit.
| HTTP | type | When |
|---|---|---|
400 | invalid_request_error | The request is well-formed JSON but wrong: unknown built-in model, invalid feature schema, a slug or filter conflict, an oversized tensor, JSON nested more than 64 levels deep (too_deeply_nested), an endpoint address or header that can't be used (invalid_inference_url, invalid_inference_headers), a URL moving to another host with its saved credentials (inference_credentials_required), or a value that can't be stored, such as NaN or Infinity (invalid_value). An input that is NaN or infinite returns invalid_input. |
401 | authentication_error | Missing, invalid, revoked or expired credentials. |
403 | permission_error | A key where a session is needed (user_session_required), a role that does not allow the call (read_only_role for a viewer, admin_required, owner_required), a session whose organization the account has left (organization_access_revoked), a plan quota reached (quota_exceeded), or something the plan does not include, such as members in an organization that is not on Team (plan_required). |
404 | not_found_error | No object with that id or slug in your organization (model_not_found, explanation_not_found, …). |
409 | conflict_error | A slug or version label already exists (slug_taken, version_taken, email_taken), a prediction_id is already in use in this workspace (prediction_id_in_use), an invitation is no longer pending (invitation_expired, …), an organization would be left without an owner (last_owner), or a plan change that does not apply (already_on_plan, custom_plan, subscription_unsettled, no_billing_account). |
422 | invalid_request_error / engine_error | Body validation failed (validation_error, with every error in details.errors), or the model cannot be explained as asked (no_reference_population, missing_value_not_supported from LIME or a counterfactual on a row with a gap, non_finite_output when its output for that input isn't a finite number, model_not_runnable, unsupported_layers, invalid_input). |
413 | invalid_request_error | The request body is too large (payload_too_large): 1 MiB without valid credentials and 128 MiB with them. Send more reference rows in several calls, as the Python client does, and weights through the tensor endpoint. |
429 | rate_limit_error | An hourly window is exhausted (rate_limited), or too many calls to inference endpoints are in progress at once (inference_busy). Retry-After says how many seconds to wait; details has the limit and window. |
502 | upstream_error | Your remote inference endpoint failed, answered in an unexpected shape, or sent more than 64 MB (inference_reply_too_large). Also when the payment provider could not complete a billing request (billing_provider_error); nothing was charged. |
503 | api_error | Kaimei is busy (database_busy). Retry-After says how many seconds to wait, and the Python client retries by itself where it safely can. Billing endpoints answer billing_not_configured on a server with no payment provider set up. |
500 | api_error | Something broke on our side. The response never includes internals; tell us the time and the request. |
The Python client raises kaimei.KaimeiError subclasses with the same fields: AuthenticationError, PermissionDeniedError, NotFoundError, RateLimitError, APIStatusError for everything else the API returned, and APIConnectionError when no usable response arrived. Each exposes .message, .type, .code, .param, .status_code and .details.
422 Unprocessable Entitya missing body field
{
"error": {
"type": "invalid_request_error",
"code": "validation_error",
"message": "Field required",
"param": "input",
"details": {
"errors": [
{
"type": "missing",
"loc": ["body", "input"],
"msg": "Field required",
"input": {"model": "credit-risk-v3"}
}
]
}
}
}404 Not FoundResponse
{
"error": {
"type": "not_found_error",
"code": "model_not_found",
"message": "No model found for 'no-such-model'.",
"param": "model"
}
}422 Unprocessable Entityexplaining a model with no population
{
"error": {
"type": "engine_error",
"code": "no_reference_population",
"message": "This model has no reference population yet. Upload reference data (PUT /v1/models/{id}/reference-data), log some predictions, or give every feature a baseline."
}
}from kaimei import Kaimei, NotFoundError, RateLimitError, KaimeiError
try:
client.explanations.create(model="no-such-model", input=row)
except NotFoundError as err:
print(err.code, err.param) # model_not_found model
except RateLimitError as err:
print(err.details) # {'limit': 120, 'window_s': 3600}
except KaimeiError as err:
print(err.status_code, err.type, err.message)