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.
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, withreason"withdrawn"and itsaccession; 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; alsoplasticdb_authentication, signalled before anything is sent.plasticdb_merged: the accession was merged (the server answers 301); alsoplasticdb_gone(merged_into,location, andkind, what the survivor is:"wild_type","engineered"or"microorganism").plasticdb_engineered_variant: a per-protein call given a variant's accession; alsoplasticdb_not_found(accession,location, andmerged_intowhen the variant was merged too).plasticdb_results_expired: a job's result files were deleted under the retention policy (410expired); alsoplasticdb_gone(results_expired_at). Its record and hits stay readable.plasticdb_validation(422): a parameter was invalid (errors, each with itsloc,msgandtype).plasticdb_idempotency_key_reused: a submission'sidempotency_keywas used before for a different request; alsoplasticdb_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 withreason"timeout");plasticdb_service_unavailable(503, also a server error;retry_after, andreason:archive_unavailablewhile the dataset ZIP is built,index_unavailableorbinary_unavailablefor the sequence search).plasticdb_job_error: a problem with a job (job);plasticdb_job_failed: it finished with statuserror(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, withplasticdb_release_unknown(404unknown, also not found),plasticdb_release_no_artefacts(404no_artefacts, also not found) andplasticdb_release_not_mounted(503not_mounted, also service unavailable); andplasticdb_release_unsupported, the release cannot answer this call, withplasticdb_release_live_only(409live_only, also a conflict) andplasticdb_release_unsupported_filter(422release_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