opencitations_client/error.rs
1use std::result;
2use thiserror::Error as ThisError;
3
4/// A type alias for handling errors throughout this crate.
5pub type Result<T> = result::Result<T, Error>;
6
7/// Everything that can go wrong talking to OpenCitations.
8///
9/// Note what is *not* here: an identifier OpenCitations holds nothing about is
10/// not an error. Both apis answer such a request with `200` and an empty list,
11/// so a lookup that found nothing comes back as an empty [`Vec`] and a count of
12/// zero. See [`Error::NoSuchOperation`] for the case that does fail.
13#[derive(Debug, ThisError)]
14#[non_exhaustive]
15pub enum Error {
16 /// an identifier that is not `scheme:value`
17 ///
18 /// OpenCitations addresses everything by a prefixed identifier -- a bare
19 /// `10.1016/j.marpol.2021.104855` means nothing to it, `doi:` in front of
20 /// it does. The prefix is required here rather than guessed at, because a
21 /// guess that picks the wrong scheme is answered with an empty list and
22 /// reads exactly like a work nobody has cited.
23 #[error(
24 "`{given}` is not a `scheme:value` identifier; write it as `doi:{given}` or `pmid:{given}`"
25 )]
26 UnprefixedIdentifier {
27 /// the identifier as it was written
28 given: String,
29 },
30
31 /// an identifier whose scheme or value is empty, e.g. `doi:` or `:10.1016`
32 #[error("`{given}` is not an identifier: {why}")]
33 InvalidIdentifier {
34 /// the identifier as it was written
35 given: String,
36 /// what is wrong with it
37 why: &'static str,
38 },
39
40 /// a string that is not an Open Citation Identifier
41 ///
42 /// An OCI is the two OMIDs of the citing and cited work joined by a `-`,
43 /// e.g. `06024047477-06220256775`.
44 #[error("`{given}` is not an open citation identifier: {why}")]
45 InvalidOci {
46 /// the identifier as it was written
47 given: String,
48 /// what is wrong with it
49 why: &'static str,
50 },
51
52 /// OpenCitations answered a route it does not serve
53 ///
54 /// Answered with a `404` and a plain-text body rather than json, which is
55 /// what an identifier it could not even parse produces -- `citations/foo`
56 /// rather than `citations/doi:foo`.
57 #[error("opencitations serves no such operation: {message}")]
58 NoSuchOperation {
59 /// the body it answered with, trimmed
60 message: String,
61 },
62
63 /// OpenCitations refused the request
64 ///
65 /// The body is passed through as it arrived, because it is sometimes json
66 /// and sometimes plain text and neither shape is documented.
67 #[error("opencitations answered {status}: {body}")]
68 Api {
69 /// the status it answered with
70 status: u16,
71 /// the body it answered with, trimmed
72 body: String,
73 },
74
75 /// OpenCitations kept answering `429` until the retry budget ran out
76 ///
77 /// The client paces itself well inside the documented 180 requests a
78 /// minute, so this normally means requests are also being made from
79 /// somewhere else on the same address -- another process, or another
80 /// [`OpenCitations`](crate::OpenCitations) built separately rather than
81 /// cloned.
82 #[error("opencitations rate limited the request; gave up after {attempts} attempts")]
83 RateLimited {
84 /// how many times the request was sent
85 attempts: u32,
86 },
87
88 /// a response this crate could not read
89 ///
90 /// Every field of both apis arrives as a string, including the ones that
91 /// are plainly numbers and dates, so this is where an unannounced change of
92 /// shape surfaces.
93 #[error("could not read the {what} in opencitations' answer: {source}")]
94 Malformed {
95 /// which part of the response was unreadable
96 what: &'static str,
97 /// the underlying deserialization error
98 source: serde_json::Error,
99 },
100
101 /// an error that occurred while operating with [reqwest]
102 #[error(transparent)]
103 ReqWest {
104 /// the underlying transport error
105 #[from]
106 reqwest: reqwest::Error,
107 },
108
109 /// the client could not be built
110 #[error("{msg}")]
111 Config {
112 /// what could not be configured
113 msg: String,
114 },
115}