Using the API
Errors
Every error from /lms/v1 is an RFC 9457 problem with Content-Type: application/problem+json:
{
"type": "https://api.librarika.dev.raynux.com/problems/hold_limit_reached",
"title": "Hold limit reached",
"status": 422,
"code": "hold_limit_reached",
"detail": "Sorry, you have reached your hold limit.",
"request_id": "01JD8Q3W6Y2N5K7M9P0R4S6T8V"
}
codeis the stable machine code. Match oncode, never ondetailortitle.typeishttps://api.librarika.dev.raynux.com/problems/<code>, the code's page on this site. Every code has a page.titleis the code in words and never changes.detailsays what happened, translated into the request's language (Accept-Language). Show it to people; do not parse it.request_idequals the response'sX-Request-ID. Log it, and quote it to support.errors, onvalidation_failed, lists each failing field:pointer(RFC 6901, into the body; a header keeps its location, such asheader.Idempotency-Key), a fieldcodeand adetail.- A
429addslimitandwindow_seconds.
Codes are added within v1 but never removed or redefined. Treat a code you do not know by its HTTP status.
Status codes
| Status | Meaning | Examples |
|---|---|---|
400 |
The request is malformed or misses a required header | bad_request, idempotency_key_required, invalid_cursor, page_too_deep, credential_in_url |
401 |
No usable credential | invalid_token, token_expired, dpop_invalid |
403 |
The credential may not do this | insufficient_scope, wrong_flow, library_not_enabled, feature_disabled, forbidden |
404 |
Not found, or not yours to see | not_found |
405 |
The path does not take this method; Allow lists those it takes, OPTIONS included |
method_not_allowed |
406 |
The Accept header cannot be satisfied |
not_acceptable |
409 |
A conflict with the resource's current state | already_on_hold, email_taken, idempotency_in_progress |
412 |
If-Match does not match the current ETag |
precondition_failed |
413 |
The body is over 16 KiB | payload_too_large |
415 |
The body's media type is not accepted; on a PATCH the answer carries Accept-Patch: application/merge-patch+json |
unsupported_media_type |
422 |
Invalid fields, or a refusal under a library rule | validation_failed, hold_limit_reached, rule_violation |
428 |
If-Match is missing |
precondition_required |
429 |
A rate limit was hit; wait Retry-After seconds |
rate_limited, daily_quota_exceeded |
500 |
Our fault; the body never carries the cause | internal_error |
503 |
A dependency is briefly unavailable | auth_unavailable, search_unavailable, rate_limit_unavailable |
409 or 422
A 409 means the resource's current state is in the way: the member already holds the title, the email belongs to another member. Reading the current state shows why. A 422 with a business code means a library rule refuses the action: the member reached their hold limit, the title cannot be held. Reading the state does not change the answer; the rule or the member's situation has to change. Neither is worth retrying unchanged.
A cancel, activate or deactivate on a resource that is already in the target state is not an error: it answers 200 with the resource unchanged.
404 for what is not yours
An id that belongs to another library, another member's loan or hold, or a title the library does not publish answers 404 not_found, exactly like an id that does not exist.
Authentication errors
A 401 carries WWW-Authenticate (Bearer, or DPoP for a DPoP-bound token) with resource_metadata and, when a credential was sent, error. resource_metadata is the URL of the API's OAuth protected-resource metadata (RFC 9728), which names the authorization server and the scopes. A 403 insufficient_scope names the needed scope.
The OAuth endpoints (/oauth2/token, /oauth2/revoke, /oauth2/par) answer OAuth errors, not problems: see Tokens.
Retrying
| Answer | Retry? |
|---|---|
429 |
after Retry-After seconds |
409 idempotency_in_progress |
after Retry-After, with the same Idempotency-Key |
500, 503 |
with exponential backoff and jitter; a write with the same Idempotency-Key |
401 token_expired |
after refreshing the token |
any other 4xx |
not until you change the request, the credential or the data |
See Rate limits and Idempotency.