Struct ApiError 

pub struct ApiError {
    status: StatusCode,
    body: ErrorBody,
    headers: Vec<(HeaderName, HeaderValue)>,
}

A failure rendered as an HTTP status plus an ErrorBody.

Fields

status: StatusCode

body: ErrorBody

headers: Vec<(HeaderName, HeaderValue)>

Extra response headers, such as WWW-Authenticate or DPoP-Nonce.

A client’s next move after AuthenticationRequired, ExpiredToken and InvalidToken differs — ask for a credential, refresh, or give up — and a header is how it learns which without parsing the message. Empty for almost every error this crate raises, which is why it is a field rather than a second constructor for every variant above.

Implementations

impl ApiError

pub fn new( status: StatusCode, error: impl Into<String>, message: impl Into<String>, ) -> Self

Builds an error response from its parts.

pub fn with_header(self, name: HeaderName, value: impl Into<String>) -> Self

Attaches a response header, such as WWW-Authenticate.

pub fn bad_request(message: impl Into<String>) -> Self

A 400 for a body that did not parse or did not make sense.

pub fn repo_not_found(repo: &str) -> Self

No repository here, under either a DID or a handle.

RepoNotFound is spelled as atproto’s own personal data server spells it. The com.atproto.repo.* lexicons declare no error for it — only RecordNotFound and InvalidSwap — but every com.atproto.sync.* lexicon that can miss a repository declares this name, and the reference implementation raises it from describeRepo, deleteRecord and putRecord alike. Inventing a second spelling for the same condition is the failure this constructor exists to avoid.

404 rather than the reference implementation’s 400. XRPC clients switch on the name and not the status, the name is the one they know, and “not found” is what the status field is for.

pub fn repo_mismatch(authenticated: &str, repo: &str) -> Self

The authenticated agent is not the one the repository belongs to.

RepoMismatch, its own name rather than a reused one: an agent token is real and unexpired — ApiError::new with AuthenticationRequired, ExpiredToken or InvalidToken is what a route answers before this is ever reached — and the caller needs to know that what failed is whose repository this is, which no retry of the same credential against the same repository can fix. plan/auth-types.md treats “an agent never writes another agent’s repository” as an invariant rather than a policy knob, and this is where it is enforced: routes::write_record and its siblings compare the DID auth::require_agent_token resolved against the repository the request names, before any write reaches the registry.

pub fn account_mismatch(authenticated: &str, target: &str) -> Self

The authenticated agent is not the account this admin route names.

AccountMismatch, its own name for the same reason Self::repo_mismatch has one: an agent token is real and unexpired, and what failed is whose account this is. Every account-lifecycle mutation is self-service — an agent’s own credential, checked against the account the request names, is the whole of what authorizes them; see plan/auth-types.md. This is what that credential gets for naming somebody else’s account.

pub fn rate_limited(message: impl Into<String>) -> Self

A caller has exceeded a rate limit; see crate::rate_limit.

RateLimitExceeded names no error the lexicons declare — the same position MethodNotImplemented’s own doc note (routes::unknown_route) describes for a route that does not exist at all. 429 is the standard HTTP status for this and every client is expected to already know it even when the name is new to it.

pub fn account_cap_reached(cap: u64) -> Self

This deployment already holds as many accounts as its operator has configured room for.

Its own name rather than Halted: that name says a stop was thrown, by an operator or by this server when its operator’s record is missing, and neither is true of a full deployment — an account leaving, or an operator raising the cap, both clear this without anyone having pulled anything. 503, the same posture ProvisionError::WriteQueueFull takes: a statement about the deployment, not about the caller.

pub fn not_ready(route: &str, snapshot: &LifecycleSnapshot) -> Self

This deployment has not finished being born, or has lost its public standing, and the route asked for is one it therefore defers.

503 with Retry-After, and an error name — ServerNotReady — no lexicon declares, the same position RateLimitExceeded above is in. The status and the header are what a caller actually reads, and both are standard.

What a relay is meant to conclude

Three conditions a crawler has to tell apart, and this is exactly one of them:

• Try later — this. 503, a Retry-After, a named reason. The server is fine and is not finished. Retry on the hint.
• Broken — a refused connection, a 502 from something in front, or a 500 with no Retry-After. Nothing emits a 500 for this condition, which is what makes the absence of the header meaningful.
• Nothing here — 200 with an empty list or stream. Fine, and holds nothing. Nothing to retry.

Never a 404: “this method does not exist” and “this method is not ready” are facts a relay reacts to completely differently, and only one of them is worth ever asking about again.

The message names the state, which for an unclaimed server is the whole answer: nobody is currently answerable for this deployment, and the fix is to run didbot operate.

pub fn record_not_found(uri: &str) -> Self

The repository is here and the record is not.

Declared by com.atproto.repo.getRecord, which is the one route that returns it: deleteRecord is specified to succeed when the record was already absent.

pub fn status(&self) -> StatusCode

The status this error responds with.

pub fn error(&self) -> &str

The machine-readable error name.

pub fn message(&self) -> &str

The human-readable message.

Trait Implementations

impl Clone for ApiError

fn clone(&self) -> ApiError

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ApiError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<&ProvisionError> for ApiError

fn from(err: &ProvisionError) -> Self

Maps a provisioning failure onto a status and an error name.

The Display text of the underlying error becomes the message. Every error in the chain is written for the caller to read: a secret, a signing key and the path to a file this deployment keeps are each kept out of it, and a store refusal carries only the sizes and the sentence that are about the request itself.

impl From<Halted> for ApiError

The name a request gets when the e-stop has halted it.

Halted rather than a generic MethodNotImplemented or an ordinary 503: atproto clients that do not know the name still see a clear “unavailable”, and plan/e-stop.md’s own requirement is that the ones that do know it can tell a halt apart from every other reason a request might fail. The message says whose latch it is, because that decides whether waiting helps: an operator’s stop stays until the operator releases it, and this server’s own pause lifts when the operator’s record is back. Either way, retrying before then does not.

fn from(halted: Halted) -> Self

Converts to this type from the input type.

impl IntoResponse for ApiError

fn into_response(self) -> Response

Create a response.

impl PartialEq for ApiError

fn eq(&self, other: &ApiError) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for ApiError

impl StructuralPartialEq for ApiError