Librarika Hubfor developers Test environment
Menu

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"
}
  • code is the stable machine code. Match on code, never on detail or title.
  • type is https://api.librarika.dev.raynux.com/problems/<code>, the code's page on this site. Every code has a page.
  • title is the code in words and never changes.
  • detail says what happened, translated into the request's language (Accept-Language). Show it to people; do not parse it.
  • request_id equals the response's X-Request-ID. Log it, and quote it to support.
  • errors, on validation_failed, lists each failing field: pointer (RFC 6901, into the body; a header keeps its location, such as header.Idempotency-Key), a field code and a detail.
  • A 429 adds limit and window_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.