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.
`401`	authentication_error	Missing, invalid, revoked or expired credentials.
`403`	permission_error	A key where a session is needed, a non-admin changing the organization, or a plan quota reached (`quota_exceeded`).
`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`).
`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`, `model_not_runnable`, `unsupported_layers`, `invalid_input`).
`429`	rate_limit_error	An hourly window is exhausted (`rate_limited`). `Retry-After` says how many seconds to wait; `details` has the limit and window.
`502`	upstream_error	Your remote inference endpoint failed or answered in an unexpected shape.
`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)