Errors

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.

HTTPtypeWhen
400invalid_request_errorThe 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.
401authentication_errorMissing, invalid, revoked or expired credentials.
403permission_errorA 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).
404not_found_errorNo object with that id or slug in your organization (model_not_found, explanation_not_found, …).
409conflict_errorA 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).
422invalid_request_error / engine_errorBody 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).
413invalid_request_errorThe 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.
429rate_limit_errorAn 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.
502upstream_errorYour 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.
503api_errorKaimei 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.
500api_errorSomething 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)