Errors

{
  "code": "dataset_too_large",
  "category": "validation",
  "problem": "The dataset exceeds the V1 size ceiling.",
  "cause": "Rows x columns are above the benchmarked limit this engine can serve.",
  "fix": "Reduce the dataset below the published max rows/columns and retry.",
  "docUrl": "https://hollerith.dev/docs/errors#dataset_too_large",
  "retryable": false,
  "requestId": "req_9f2c41ab7d0e5c83"
}

That is the envelope, returned with the HTTP status listed for the code. There are 26 codes, defined once in a shared contract and mirrored by the Python SDK.

The envelope

code — the stable identifier, one of 26. The only field to branch on.
category — one of eight. It selects the SDK exception class.
problem, cause, fix — what went wrong, why, and what to do. Written for a human.
docUrl — the documentation anchor for this code.
retryable — true for four codes. See Retrying.
requestId — req_ plus 16 hex characters, logged server-side under the same id.

Branch on code. Never branch on message text — problem, cause and fix are written for a human and the server rewrites them per instance, so a malformed CSV names the offending row and column in its cause.

Not every error is an envelope

{"error": "invalid_json"}

A request body that fails to parse, or that matches none of the accepted shapes, returns a bare 400 like that one — or {"error":"invalid_request"}. No code, no category, no requestId. So “every error carries a request id” is false. Typed envelopes carry one; malformed input does not, and there is nothing to quote to support.

The SDK cannot type these. With no code to resolve, it falls back to the base HollerithError carrying the text An unexpected error occurred. An except ValidationError block will not catch it.
Catch HollerithError at the outer edge of any integration, not only the subclasses you expect.
A 400 with no code means the body shape was wrong, most often a misspelled field. A typo in the inline POST /v1/predictions body falls through to the context-backed parser and returns invalid_request without saying which shape failed.

Categories and SDK exceptions

The category field, not the code, selects the exception class. Eight categories, eight classes, all subclassing HollerithError.

Category	HTTP	Exception
auth	401	`AuthenticationError`
permission	403	`PermissionDeniedError`
quota	429	`QuotaExceededError`
validation	413, 422	`ValidationError`
not_found	404	`NotFoundError`
conflict	409	`ConflictError`
unavailable	503	`ServiceUnavailableError`
server	500	`ServerError`

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.retryable)            # False for quota_exceeded
except HollerithError as exc:
    print(exc.request_id)           # None when the SDK raised it locally

Every exception exposes code, problem, cause, fix, doc_url, retryable and request_id. Printing one renders all of them on separate lines.

The catalogue

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

auth — 401, `AuthenticationError`

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

permission — 403, `PermissionDeniedError`

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

quota — 429, `QuotaExceededError`

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

validation — 413 and 422, `ValidationError`

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

fitted_context_incompatible is a validation error, not a not_found one, despite its name sitting beside three context codes below. It raises ValidationError.

not_found — 404, `NotFoundError`

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

Reading /v1/predictions/{id}/result before the job succeeds returns job_not_found, not a 409 or a 425. Poll the job until its status is succeeded, then read the result.

conflict — 409, `ConflictError`

Code	Category	HTTP	Retryable	What to do
`idempotency_conflict`	conflict	409	no	Use a fresh idempotency key, or resend the identical original request.

unavailable — 503, `ServiceUnavailableError`

Code	Category	HTTP	Retryable	What to do
`worker_warming_up`	unavailable	503	yes	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`	unavailable	503	yes	Retry shortly.
`cache_unavailable`	unavailable	503	yes	Retry shortly; if it persists, call `fit()` again to rebuild the context.

worker_warming_up is defined in the contract but nothing in the control plane emits it. A cold or unreachable worker reaches you as worker_unavailable instead, which the SDK also raises itself when it cannot reach the API or object storage.

server — 500, `ServerError`

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

Retrying

Exactly four codes are retryable: rate_limited, worker_warming_up, worker_unavailable and cache_unavailable. Retry those, unchanged. Every other code will return the same answer however many times you send it. quota_exceeded is a 429 that is not retryable. A client that retries on status code rather than on the retryable field will loop against it until the daily reset. The SDK has no backoff-retry layer. What it does is narrower than that, in three ways:

Only ServiceUnavailableError with retryable=true is absorbed. A QuotaExceededError is raised to you on the first occurrence.
Only inside a poll loop. A 503 on the call that submits the job reaches you; a 503 while polling an already-submitted job is swallowed.
At a fixed poll_interval, default 1.0 second, with no exponential growth, until timeout (default 900.0 seconds) lapses and a TimeoutError is raised.

One asymmetry to know: while predict() and evaluate() always absorb a retryable 503 during polling, fit() only does so when you pass on_warming=. Without that hook, a transient warm-up during a fit wait propagates.

clf.fit(train, target="churned", on_warming=lambda e: print(e.problem))

Rate limiting and daily quota are yours to handle. Nothing in the SDK spaces out your calls.

Two codes that carry more than one meaning

`training_ref_expired`

One code, two situations: the staged input for a job expired before the worker read it, and a succeeded job whose result aged out. The first needs a re-run, the second means you read the result too late. Scored predictions and evaluation metrics live for 1 hour. Fetch them inside that window or re-run the job.

`rate_limited`

This code is currently never emitted. No rate limiter is wired for the public API, so it is defined and typed but unreachable today. Handle it anyway. It costs one branch, and its retryable flag is true when it does arrive.

When you contact support

Send the requestId. The API logs the same id server-side against the failing request, so it is the fastest way to the exact log line.

An unexpected error occurred.
  Cause: The server hit a condition it did not handle.
  Fix:   Retry; if it persists, contact support with the requestId.
  Docs:  https://hollerith.dev/docs/errors#internal_error
  Request: req_9f2c41ab7d0e5c83

Two cases have no id to send. A bare invalid_json or invalid_request response carries none, and errors the SDK raises before any request — missing_api_key is the common one — have request_id set to None. Quote the code and the call you made instead.

Limits — the ceilings behind dataset_too_large and payload_too_large
The fitted context — expiry, and the three context codes
Usage and billing — what quota_exceeded is counting
Troubleshooting — symptoms rather than codes

Get started

Concepts

Guides

Reference

Account

Help

The envelope

Not every error is an envelope

Categories and SDK exceptions

The catalogue

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`

Retrying

Two codes that carry more than one meaning

`training_ref_expired`

`rate_limited`

When you contact support

​The envelope

​Not every error is an envelope

​Categories and SDK exceptions

​The catalogue

​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

​Retrying

​Two codes that carry more than one meaning

​training_ref_expired

​rate_limited

​When you contact support

​Related

The envelope

Not every error is an envelope

Categories and SDK exceptions

The catalogue

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`

Retrying

Two codes that carry more than one meaning

`training_ref_expired`

`rate_limited`

When you contact support

Related