Errors

Every artifact failure raises MetranaArtifactError or one of its subclasses, so you can catch broadly or narrowly. They all live in metrana.utils.exceptions. Response bodies are never included in error messages.

from metrana.utils.exceptions import MetranaArtifactError

try:
    metrana.download_artifact("model", "llm", dest="./m")
except MetranaArtifactError as e:      # catches every artifact failure
    ...

The hierarchy

Exception	Raised when
MetranaArtifactError	Base for every artifact failure — catch this to handle any of them.
MetranaArtifactAuthError	The API rejected the credentials or scope (401/403): key missing/invalid, lacks artifacts:read / artifacts:write, or not bound to the workspace.
MetranaArtifactNotFoundError	The artifact, version, alias, or workspace doesn’t exist for this key (404).
MetranaArtifactConflictError	The operation conflicts with the version’s state (409) — e.g. committing while a blob’s bytes are still missing.
MetranaArtifactQuotaError	The upload would exceed a per-version or per-workspace storage ceiling (413).
MetranaArtifactValidationError	The request was rejected as invalid (400/422): empty inputs, duplicate manifest paths, both alias and version_index given, a missing workspace, a malformed digest, …
MetranaArtifactChecksumError	Uploaded bytes didn’t hash to the declared SHA-256 (422 at multipart completion). Subclasses MetranaArtifactValidationError.
MetranaArtifactTransferError	A direct client↔storage transfer (presigned PUT/part/GET) failed after exhausting retries, or a download couldn’t be verified.
MetranaArtifactFileChangedError	A local file changed size mid-upload during a multipart transfer.
MetranaArtifactAliasError	The version committed, but one or more requested aliases couldn’t be applied — see below.
NoMetranaApiKeyError	No api_key argument and METRANA_API_KEY is unset. (Shared with the ingestion SDK.)

MetranaArtifactAliasError — the version is safe

Raised by upload_artifact when the upload succeeded and committed but pointing an alias at it failed. The committed version is safe; only the alias step failed. The error carries the details you need to retry just that step:

from metrana.utils.exceptions import MetranaArtifactAliasError

try:
    metrana.upload_artifact("ckpt/", type="model", name="llm", aliases=["production"])
except MetranaArtifactAliasError as e:
    e.version_index   # the safe, committed version index
    e.applied         # aliases that were set
    e.failed          # aliases that were not
    for alias in e.failed:
        metrana.set_artifact_alias(
            type="model", name="llm", alias=alias, version_index=e.version_index,
        )

Because the subclasses form a tree, you can be as specific as you like — catch MetranaArtifactAuthError to handle a bad key, or just MetranaArtifactError to handle everything. Transient failures (429 / 5xx / connection drops) are retried with backoff internally, so what surfaces is a genuine, non-recoverable condition.