Skip to content

Errors

Every exception subclasses plasticdb.PlasticDBError, which carries message, status_code, the server's detail, the parsed body and the response. Some classes have two parents on purpose, so except NotFoundError also catches an unknown release and except ValidationError also catches a filter a release cannot answer.

try:
    client.proteins.get("PB0000")
except plasticdb.MergedError as exc:  # check subclasses before their parents
    print("use", exc.merged_into)
except plasticdb.NotFoundError:
    ...
except plasticdb.PlasticDBError as exc:
    print(exc.status_code, exc.message)

Hierarchy

PlasticDBError
├─ APIConnectionError                    server unreachable, or the connection broke
│  └─ APITimeoutError                    the request timed out
├─ UnexpectedResponseError               the server answered something not understood
├─ BadRequestError                       400
├─ AuthenticationError                   401   no key, or an invalid or expired one
├─ PermissionDenied                      403   valid key, not allowed
├─ NotFoundError                         404
│  ├─ UnknownReleaseError                404   no completed release has that version *
│  ├─ ReleaseNoArtefactsError            404   the release predates its artefacts *
│  └─ EngineeredVariantError             404/301  the accession is a variant, not a wild type
├─ GoneError                             410   withdrawn record (.accession), expired share link
│  ├─ MergedError                        301   merged; .merged_into is the survivor, .kind
│  └─ ResultsExpiredError                410   a job's result files expired (.results_expired_at)
├─ ConflictError                         409
│  └─ LiveOnlyError                      409   endpoint cannot be pinned to a release *
├─ PayloadTooLargeError                  413   upload over the size limit
├─ ValidationError                       422   .errors lists the problems
│  ├─ UnsupportedFilterError             422   a past release cannot answer this filter *
│  └─ IdempotencyKeyReusedError          422   an Idempotency-Key reused for another request
├─ RateLimitError                        429   .retry_after (seconds)
├─ ServerError                           5xx   (.reason "timeout": a sequence search's 504)
│  └─ ServiceUnavailableError            503   .retry_after, .reason
│     └─ ReleaseNotMountedError          503   the release's files are not readable there *
├─ ChecksumError                         a download did not match its published SHA-256
├─ ReleaseError                          * every starred class is also a ReleaseError
│  ├─ ReleaseNotAvailableError           unknown, no artefacts, or not mounted
│  └─ ReleaseUnsupportedError            exists, but cannot answer this endpoint or parameter
└─ JobError                              .job
   ├─ JobFailedError                     the job finished with status "error"
   └─ JobTimeoutError                    wait(timeout=) ran out (also a TimeoutError)

Every error carries .reason when the server's body had one (withdrawn, expired, engineered_variant, archive_unavailable, index_unavailable, timeout, the release reasons…), next to .status_code, .detail and .body. Every class here is importable from plasticdb itself (plasticdb.GoneError).

Starred classes have two parents (their HTTP class and a ReleaseError branch); ReleaseError carries .release, .current_release and .reason. MergedRecordWarning (a UserWarning) is issued when follow_merges=True returns a survivor.

HTTP status to exception

Status Exception
301 reason: merged MergedError (a GoneError); followed with follow_merges=True
301 reason: engineered_variant followed by proteins.get() / fasta() / structure() to the variant; EngineeredVariantError elsewhere
400 BadRequestError
401 AuthenticationError (also raised locally before a job is sent without a key)
403 PermissionDenied
404 NotFoundError; UnknownReleaseError or ReleaseNoArtefactsError when a release is the cause; EngineeredVariantError for engineered_variant
409 ConflictError; LiveOnlyError for live_only
410 GoneError (reason: withdrawn, .accession); ResultsExpiredError for expired
413 PayloadTooLargeError (a size limit, or more than 20 genomes)
422 ValidationError; UnsupportedFilterError for release_unsupported; IdempotencyKeyReusedError for idempotency_key_reused
429 RateLimitError (after the retry budget)
5xx ServerError; ServiceUnavailableError for 503; ReleaseNotMountedError for not_mounted
no response APIConnectionError / APITimeoutError

Retries: 429s are retried after Retry-After (up to max_retry_wait). Reads, sequence searches and submissions are retried with backoff on 5xx, timeouts and connection errors (max_retries, default 3): a submission (job, tree, share link) carries one Idempotency-Key across all its attempts, so a retry that reaches the server twice gets the first result back rather than a duplicate (Jobs). A 503 not_mounted and a sequence search's 504 timeout are not retried; a 503 whose Retry-After exceeds max_retry_wait (the dataset archive's 120 s) raises at once.

Exit codes on the command line

The CLI maps exceptions to exit codes: releases to 6, a failed job to 7, timeouts (also a sequence search's 504) to 8, authentication to 4, rate limits to 5, missing, withdrawn or merged records and expired job files to 3, bad input (including 422, 400, 413 and EngineeredVariantError) to 2, server trouble to 9, anything else to 1.