Skip to content

Errors

See Errors for how they map to HTTP statuses.

errors

Exceptions raised by the PlasticDB client.

Every error is a PlasticDBError. HTTP errors carry the status code, the server's detail, the parsed body and its machine-readable reason when it sent one (withdrawn, expired, archive_unavailable, timeout…). Some classes inherit from two parents so that except NotFoundError also catches an unknown release, and except ValidationError also catches a filter a release cannot answer.

PlasticDBError

PlasticDBError(message: str, *, status_code: int | None = None, detail: Any = None, body: Any = None, response: Response | None = None)

Bases: Exception

Base class for every error this package raises.

APIConnectionError

APIConnectionError(message: str, *, status_code: int | None = None, detail: Any = None, body: Any = None, response: Response | None = None)

Bases: PlasticDBError

The server could not be reached, or the connection broke mid-request.

APITimeoutError

APITimeoutError(message: str, *, status_code: int | None = None, detail: Any = None, body: Any = None, response: Response | None = None)

Bases: APIConnectionError

The request timed out.

UnexpectedResponseError

UnexpectedResponseError(message: str, *, status_code: int | None = None, detail: Any = None, body: Any = None, response: Response | None = None)

Bases: PlasticDBError

The server answered something this client does not understand.

BadRequestError

BadRequestError(message: str, *, status_code: int | None = None, detail: Any = None, body: Any = None, response: Response | None = None)

Bases: PlasticDBError

400: the request was malformed.

AuthenticationError

AuthenticationError(message: str, *, status_code: int | None = None, detail: Any = None, body: Any = None, response: Response | None = None)

Bases: PlasticDBError

401: no credential, or an invalid or expired API key.

PermissionDenied

PermissionDenied(message: str, *, status_code: int | None = None, detail: Any = None, body: Any = None, response: Response | None = None)

Bases: PlasticDBError

403: the credential is valid but may not do this.

NotFoundError

NotFoundError(message: str, *, status_code: int | None = None, detail: Any = None, body: Any = None, response: Response | None = None)

Bases: PlasticDBError

404: no such record (or no such release, see UnknownReleaseError).

GoneError

GoneError(message: str, *, status_code: int | None = None, detail: Any = None, body: Any = None, response: Response | None = None)

Bases: PlasticDBError

410: the record was withdrawn, a job's result files expired, or a share link did.

A withdrawn protein, variant or organism has reason == "withdrawn" and accession set (a variant is withdrawn with its parent protein, too).

ResultsExpiredError

ResultsExpiredError(message: str, *, results_expired_at: datetime | None = None, **kwargs: Any)

Bases: GoneError

410 expired: the job's result files were deleted under the retention policy.

results_expired_at is when (the job record, its hits and its summary remain).

MergedError

MergedError(message: str, *, merged_into: str, location: str | None = None, kind: str | None = None, **kwargs: Any)

Bases: GoneError

The accession was merged into another record (the server answers 301).

merged_into is the surviving accession and location the API path that serves it. kind is what the survivor is: "wild_type", "engineered" (a variant) or "microorganism".

EngineeredVariantError

EngineeredVariantError(message: str, *, accession: str, location: str | None = None, merged_into: str | None = None, **kwargs: Any)

Bases: NotFoundError

The accession names an engineered variant, not a wild-type protein.

The server answers /proteins/{accession} for a variant with a 301 (reason: engineered_variant) to /variants/{accession}; get follows it and returns the Variant. The per-protein sub-collections (interactions, kinetics, properties, variants) answer a 404 with the same reason, raised as this error, because variants have none. accession is the variant, location its path and merged_into the surviving variant when the accession was also merged.

MergedRecordWarning

Bases: UserWarning

Issued when get(..., follow_merges=True) returns a merge survivor.

ConflictError

ConflictError(message: str, *, status_code: int | None = None, detail: Any = None, body: Any = None, response: Response | None = None)

Bases: PlasticDBError

409.

PayloadTooLargeError

PayloadTooLargeError(message: str, *, status_code: int | None = None, detail: Any = None, body: Any = None, response: Response | None = None)

Bases: PlasticDBError

413: an upload is over the server's per-file or per-job size limit.

ValidationError

ValidationError(message: str, *, status_code: int | None = None, detail: Any = None, body: Any = None, response: Response | None = None)

Bases: PlasticDBError

422: a parameter was invalid. errors is the server's list of problems.

IdempotencyKeyReusedError

IdempotencyKeyReusedError(message: str, *, status_code: int | None = None, detail: Any = None, body: Any = None, response: Response | None = None)

Bases: ValidationError

422 idempotency_key_reused: the key was already used for a different request.

A job, tree or share-link submission sent with the Idempotency-Key of an earlier one (within 24 hours) must repeat that request exactly; use a new key for a new submission.

RateLimitError

RateLimitError(message: str, *, retry_after: float | None = None, **kwargs: Any)

Bases: PlasticDBError

429: too many requests. retry_after is in seconds, when the server said.

ServerError

ServerError(message: str, *, status_code: int | None = None, detail: Any = None, body: Any = None, response: Response | None = None)

Bases: PlasticDBError

5xx: the server failed.

A synchronous sequence search past the server's 15 seconds is a 504 with reason == "timeout" (submit an annotate_gene job instead); a DIAMOND failure is a 502.

ServiceUnavailableError

ServiceUnavailableError(message: str, *, retry_after: float | None = None, **kwargs: Any)

Bases: ServerError

503: the server, or a service it depends on, is temporarily unavailable.

retry_after is the server's Retry-After in seconds, when it sent one, and reason what is unavailable: archive_unavailable (dataset.zip is being built), index_unavailable / binary_unavailable (the sequence search's reference database or DIAMOND).

ChecksumError

ChecksumError(message: str, *, expected: str, actual: str, **kwargs: Any)

Bases: PlasticDBError

A downloaded file did not match the SHA-256 the server published for it.

ReleaseError

ReleaseError(message: str, *, release: str | None = None, current_release: str | None = None, reason: str | None = None, **kwargs: Any)

Bases: PlasticDBError

A problem with the dataset release a request asked for.

release is the version asked for, current_release the one the server is serving (when it said), and reason the server's machine-readable code.

ReleaseNotAvailableError

ReleaseNotAvailableError(message: str, *, release: str | None = None, current_release: str | None = None, reason: str | None = None, **kwargs: Any)

Bases: ReleaseError

The release cannot answer at all: unknown, without artefacts, or not mounted.

UnknownReleaseError

UnknownReleaseError(message: str, *, release: str | None = None, current_release: str | None = None, reason: str | None = None, **kwargs: Any)

Bases: ReleaseNotAvailableError, NotFoundError

404 unknown: no completed release has that version.

ReleaseNoArtefactsError

ReleaseNoArtefactsError(message: str, *, release: str | None = None, current_release: str | None = None, reason: str | None = None, **kwargs: Any)

Bases: ReleaseNotAvailableError, NotFoundError

404 no_artefacts: the release predates its queryable artefacts.

ReleaseNotMountedError

ReleaseNotMountedError(message: str, *, release: str | None = None, current_release: str | None = None, reason: str | None = None, **kwargs: Any)

Bases: ReleaseNotAvailableError, ServiceUnavailableError

503 not_mounted: the release's files are not readable on this server.

ReleaseUnsupportedError

ReleaseUnsupportedError(message: str, *, release: str | None = None, current_release: str | None = None, reason: str | None = None, **kwargs: Any)

Bases: ReleaseError

The release exists, but cannot answer this endpoint or parameter.

LiveOnlyError

LiveOnlyError(message: str, *, release: str | None = None, current_release: str | None = None, reason: str | None = None, **kwargs: Any)

Bases: ReleaseUnsupportedError, ConflictError

409 live_only: the endpoint is computed live and cannot be pinned.

UnsupportedFilterError

UnsupportedFilterError(message: str, *, release: str | None = None, current_release: str | None = None, reason: str | None = None, **kwargs: Any)

Bases: ReleaseUnsupportedError, ValidationError

422 release_unsupported: a filter or option a past release cannot answer.

parameters names them.

JobError

JobError(message: str, *, job: Any, **kwargs: Any)

Bases: PlasticDBError

A problem with a submitted job. job is the Job.

JobFailedError

JobFailedError(message: str, *, job: Any, **kwargs: Any)

Bases: JobError

The job finished with status error; message is the server's reason.

JobTimeoutError

JobTimeoutError(message: str, *, job: Any, **kwargs: Any)

Bases: JobError, TimeoutError

Job.wait(timeout=) ran out before the job finished. The job keeps running.