Skip to contents

Every error this package raises from the API is a condition of class plasticdb_error, signalled with rlang::abort(), so it can be caught by class with tryCatch() or rlang::try_fetch(). The classes mirror the exceptions of the Python client, and a condition carries every class it belongs to: an unknown release is both a plasticdb_release_unknown and a plasticdb_not_found, and a merged record is a plasticdb_merged and a plasticdb_gone.

Value

Not a function: this page documents the condition classes.

Details

Every condition has the fields status (the HTTP status), detail (the server's message), reason (the server's machine-readable reason, when it sent one: withdrawn, expired, archive_unavailable, timeout, ...), response_body and url. The classes, most general first (extra fields in brackets):

  • plasticdb_error: any of the below.

  • plasticdb_connection_error: the server could not be reached; plasticdb_timeout: a request timed out (also a connection error).

  • plasticdb_unexpected_response: an answer this package does not understand.

  • plasticdb_bad_request (400), plasticdb_authentication (401: no, invalid or expired API key), plasticdb_permission_denied (403), plasticdb_not_found (404), plasticdb_conflict (409), plasticdb_gone (410: a withdrawn record, with reason "withdrawn" and its accession; a variant is withdrawn with its parent protein), plasticdb_payload_too_large (413: a file over the size limit, or more than 20 genomes).

  • plasticdb_api_key_required: a job function was called without an API key; also plasticdb_authentication, signalled before anything is sent.

  • plasticdb_merged: the accession was merged (the server answers 301); also plasticdb_gone (merged_into, location, and kind, what the survivor is: "wild_type", "engineered" or "microorganism").

  • plasticdb_engineered_variant: a per-protein call given a variant's accession; also plasticdb_not_found (accession, location, and merged_into when the variant was merged too).

  • plasticdb_results_expired: a job's result files were deleted under the retention policy (410 expired); also plasticdb_gone (results_expired_at). Its record and hits stay readable.

  • plasticdb_validation (422): a parameter was invalid (errors, each with its loc, msg and type).

  • plasticdb_idempotency_key_reused: a submission's idempotency_key was used before for a different request; also plasticdb_validation.

  • plasticdb_rate_limit (429) beyond the retry budget (retry_after).

  • plasticdb_server_error (5xx; a sequence search past the server's 15 seconds is a 504 with reason "timeout"); plasticdb_service_unavailable (503, also a server error; retry_after, and reason: archive_unavailable while the dataset ZIP is built, index_unavailable or binary_unavailable for the sequence search).

  • plasticdb_job_error: a problem with a job (job); plasticdb_job_failed: it finished with status error (the message is the server's reason); plasticdb_job_timeout: wait_job() ran out of time (the job keeps running on the server). Both are job errors.

  • plasticdb_checksum: a download did not match its published SHA-256 (expected, actual).

  • plasticdb_release_error: a problem with the requested release (release, current_release, reason). Its subclasses: plasticdb_release_not_available, the release cannot answer at all, with plasticdb_release_unknown (404 unknown, also not found), plasticdb_release_no_artefacts (404 no_artefacts, also not found) and plasticdb_release_not_mounted (503 not_mounted, also service unavailable); and plasticdb_release_unsupported, the release cannot answer this call, with plasticdb_release_live_only (409 live_only, also a conflict) and plasticdb_release_unsupported_filter (422 release_unsupported, also validation; parameters).

A function given an argument it does not take (an unknown filter, say) signals plasticdb_argument_error before anything is sent.

Warnings: plasticdb_merged_warning when follow_merges = TRUE returns a merge survivor, and plasticdb_release_changed when the release changed while a list was being paged.

Examples

## An unknown filter is refused before any request is sent:
res <- tryCatch(proteins_list(no_such_filter = 1),
    plasticdb_argument_error = function(e) conditionMessage(e))
cat(res)
res