Skip to main content

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}