Errors

HTTP errors

The API follows a predictable HTTP error code format. Each status maps to one SDK exception, and all of them subclass HollerithError.

401 — AuthenticationError — There is an issue with your API key (for example, it’s mistyped, revoked, or expired). See Get your API key.
403 — PermissionDeniedError — Your API key does not have permission to use the specified resource.
404 — NotFoundError — The requested job or fitted context was not found, or it aged out.
409 — ConflictError — The request conflicts with the current state of a resource, such as an idempotency key reused with a different body.
413 — ValidationError — The request exceeds the maximum allowed number of bytes.
422 — ValidationError — The request, or the table inside it, could not be processed.
429 — QuotaExceededError — Your organization has hit a rate limit, or its daily quota.
500 — ServerError — An unexpected error has occurred internal to Hollerith’s systems.
503 — ServiceUnavailableError — A worker or the cache is temporarily unavailable.

Request size limits

Limit	Maximum
Rows in the fitted table	1 000 000
Columns	2 000
Cells (rows × columns)	100 000 000
Rows scored per predict	200 000
Classes	160
Compressed upload	5 000 000 000 bytes

Exceed the upload ceiling and you get a 413 payload_too_large, raised before the table is read. Exceed any of the others and you get a 422 dataset_too_large. See Limits for the cell budget these interact through, and for the per-minute request rate behind 429.

Error shape

The API returns errors as JSON with a top-level object that always includes a code and a category value, plus a requestId for easier tracking and debugging. For example:

{
  "code": "schema_mismatch",
  "category": "validation",
  "problem": "The prediction rows do not match the fitted columns.",
  "cause": "The column tenure_months was present at fit and absent at predict.",
  "fix": "Send prediction rows with the same feature columns used to fit.",
  "requestId": "req_9f2c41ab7d0e5c83"
}

Branch on code, the stable identifier and one of 27. Never branch on problem, cause, or fix — the server rewrites those per instance. Not every error is an envelope: a body that fails to parse returns a bare {"error": "invalid_json"} with no code and no request id, which the SDK cannot type. Catch HollerithError at the outer edge of any integration, not only the subclasses you expect.

SDK error types

The Python SDK raises typed exceptions instead of returning raw JSON. Every exception exposes code, problem, cause, fix, and request_id.

from hollerith import HollerithError, QuotaExceededError, ValidationError

try:
    preds = clf.predict(rows)
except ValidationError as exc:
    print(exc.code, exc.fix)        # e.g. schema_mismatch
except QuotaExceededError as exc:
    print(exc.problem)
except HollerithError as exc:
    print(exc.request_id)           # None when the SDK raised it locally

Request ID

Every error response includes a unique x-hollerith-request-id header, and a typed error repeats it as requestId in the body. If you need to report an issue, include that value — it is logged server-side against the same request. A bare invalid_json or invalid_request response carries none, and neither do errors the SDK raises before any request goes out. Quote the code and the call you made instead.

Error codes

The What to do column is the fix string the API returns for that code.

auth — 401, `AuthenticationError`

Code	What to do
`missing_api_key`	Set `HOLLERITH_API_KEY`, or pass `api_key=` to the client.
`invalid_api_key`	Copy the key again from the console (it is shown once at creation) and retry.
`revoked_api_key`	Create a new key on the API Keys page and update your environment.
`expired_api_key`	Create a new key on the API Keys page and update your environment.
`unauthenticated`	Sign in to the console and retry; this surface requires an authenticated session.

permission — 403, `PermissionDeniedError`

Code	What to do
`org_forbidden`	Use an ID created by your own org; cross-org access is never permitted.
`subscription_required`	Contact your Hollerith administrator to change this workspace plan.

quota — 429, `QuotaExceededError`

Code	What to do
`quota_exceeded`	Wait for the daily reset shown in the usage panel, or reduce the request size.
`rate_limited`	Back off and retry after a short delay.

validation — 413 and 422, `ValidationError`

Code	What to do
`dataset_too_large`	Reduce the dataset below the published max rows/columns and retry.
`payload_too_large`	Reduce the dataset below the published maximum upload size and retry.
`malformed_csv`	Check the named row/column, fix the delimiter or encoding, and retry.
`schema_mismatch`	Send prediction rows with the same feature columns used to fit.
`missing_target_column`	Pass `target=` a column that exists in the DataFrame, then retry.
`unsupported_task`	Use a classification or regression target.
`fitted_context_incompatible`	Call `fit()` again with the current SDK/backend before predicting.

not_found — 404, `NotFoundError`

Code	What to do
`job_not_found`	Use a job id returned by this client for your org.
`training_ref_expired`	Call `fit()` again to re-stage the training set, then predict.
`fitted_context_not_found`	Use a fitted context id returned by `fit()` for this organization.
`fitted_context_expired`	Call `fit()` again to prepare a fresh context, then retry `predict()`.

conflict — 409, `ConflictError`

Code	What to do
`idempotency_conflict`	Use a fresh idempotency key, or resend the identical original request.

unavailable — 503, `ServiceUnavailableError`

Code	What to do
`worker_warming_up`	The SDK waits and retries while polling a `predict`, `evaluate` or `forecast`. A `fit` wait only does so when you pass `on_warming=`.
`worker_unavailable`	Retry shortly.
`cache_unavailable`	Retry shortly; if it persists, call `fit()` again to rebuild the context.

server — 500, `ServerError`

Code	What to do
`worker_oom`	Reduce the dataset size and retry; if it persists, contact support.
`artifact_too_large`	Re-fit with fewer training rows, then predict against the new context.
`internal_error`	Retry; if it persists, contact support with the `requestId`.

Get started

Guides

Reference

Account

Help

HTTP errors

Request size limits

Error shape

SDK error types

Request ID

Error codes

auth — 401, `AuthenticationError`

permission — 403, `PermissionDeniedError`

quota — 429, `QuotaExceededError`

validation — 413 and 422, `ValidationError`

not_found — 404, `NotFoundError`

conflict — 409, `ConflictError`

unavailable — 503, `ServiceUnavailableError`

server — 500, `ServerError`

Next steps

Troubleshooting

Limits

​HTTP errors

​Request size limits

​Error shape

​SDK error types

​Request ID

​Error codes

​auth — 401, AuthenticationError

​permission — 403, PermissionDeniedError

​quota — 429, QuotaExceededError

​validation — 413 and 422, ValidationError

​not_found — 404, NotFoundError

​conflict — 409, ConflictError

​unavailable — 503, ServiceUnavailableError

​server — 500, ServerError

​Next steps

Troubleshooting

Limits

HTTP errors

Request size limits

Error shape

SDK error types

Request ID

Error codes

auth — 401, `AuthenticationError`

permission — 403, `PermissionDeniedError`

quota — 429, `QuotaExceededError`

validation — 413 and 422, `ValidationError`

not_found — 404, `NotFoundError`

conflict — 409, `ConflictError`

unavailable — 503, `ServiceUnavailableError`

server — 500, `ServerError`

Next steps