Skip to content
The Collector
Sign in
Developer docs · Errors

Errors

Every error is a problem document (RFC 9457) with a stable code. This page explains the format and lists every code the API answers.

The problem format

Errors are sent as application/problem+json:

400 Bad Request
{
  "type": "https://collection.id/developers/errors#invalid_request",
  "title": "Bad Request",
  "status": 400,
  "detail": "Add the series title as printed on the cover.",
  "code": "invalid_request",
  "errors": [{ "path": "body.seriesTitle", "message": "Add the series title as printed on the cover." }],
  "requestId": "0b4f3b1e-6c1a-4f5e-9f0e-1f2a3b4c5d6e",
  "error": {
    "code": "invalid_request",
    "message": "Add the series title as printed on the cover."
  }
}
  • Program against code. It’s stable and snake_case; detail is written for people and may change.
  • type links the code’s entry on this page.
  • errors[] names each field that failed, as params., query. or body. followed by its path.
  • requestId is the request’s X-Request-Id: quote it to support.
  • error is the older shape ({ code, message, details }), kept so existing clients keep working. It’s deprecated in favour of code and detail.
  • A 500 internal says nothing more, on purpose: our logs have the details under its request id.

Every code

120 codes, with their statuses and what they mean. Each operation’s own codes are in the reference.

ai_budget_exhausted402

  • The plan’s AI budget for the month is used up.
1 operation answer it

already_added409

  • The copy already has this code.
  • The scan was already added as a copy.
  • The scan was already added.
4 operations answer it

already_admin409

  • Admins already work the moderation queues.
1 operation answer it

already_exists409

  • Another record has that slug.
1 operation answer it

already_held409

  • The book is already held for this collector.
1 operation answer it

already_known409

  • The catalog knows this code: change the copy to it instead.
1 operation answer it

already_member409

  • The caller is already on the team.
  • That email is already on the team.
2 operations answer it

already_processing409

  • Another match of this scan is running.
1 operation answer it

already_proposed409

  • This code is already waiting for review.
1 operation answer it

already_reported409

  • You have an open report about it already.
1 operation answer it

already_resolved409

  • Someone already resolved it.
  • It was already handled.
2 operations answer it

already_reviewed409

  • Someone already reviewed it.
  • A moderator has already reviewed it.
6 operations answer it

already_undone409

  • That change was already undone.
1 operation answer it

assistant_not_configured503

  • The assistant isn’t set up here.
1 operation answer it

audit_failed500

  • The change was made, but writing its audit row failed.
2 operations answer it

auth_update_failed502

  • The sign-in service refused the change.
1 operation answer it

batch_not_found404

  • No open session of yours with that batchId.
  • No session of yours with that id.
2 operations answer it

cannot_undo409

  • Only the copy’s latest change can be undone.
1 operation answer it

change_already_made409

  • That proposed change was already approved.
1 operation answer it

changed_since409

  • The copy changed since; undo the later change first.
1 operation answer it

checksum_failed422

  • The digits fail the barcode’s check digit.
1 operation answer it

confirmation_required400

  • Type DELETE to confirm.
1 operation answer it

csv_columns422

  • The CSV lacks the columns needed (title, number, price…).
1 operation answer it

duplicate409

  • You already have a suggestion waiting for this record.
1 operation answer it

edition_mismatch409

  • The edition isn’t one of that issue’s.
1 operation answer it

empty_patch409

  • Nothing in it can be applied any more.
1 operation answer it

entity_merged409

  • The record was merged into another one; edit the one that was kept.
3 operations answer it

entity_not_found409

  • The issue is no longer in the catalog.
  • The record it’s about no longer exists.
4 operations answer it

export_expired410

  • The export isn’t ready, or its files expired.
1 operation answer it

export_not_found404

  • No such export of yours.
2 operations answer it

export_part_not_found404

  • The export has no such part.
1 operation answer it

export_rate_limited429

  • One full export a day (details.nextAt says when the next is possible).
1 operation answer it

feature_required403

  • Changing more than one copy needs Pro.
  • The plan doesn’t include this (details.feature names it).
8 operations answer it

forbidden403

  • The upload isn’t yours.
  • That isn’t yours to change.
  • The caller’s side can’t do this (only the store answers a request…).
  • Only the store’s owners and admins can do this.
13 operations answer it

has_cover409

  • It has a cover now; decline this one or remove that cover first.
1 operation answer it

has_holds409

  • It has hold history: archive it instead.
1 operation answer it

has_questions409

  • Collectors asked about it: archive it instead.
1 operation answer it

holds_unavailable409

  • The store isn’t taking holds right now.
1 operation answer it

idempotency_in_progress409

  • The first request with this key is still running.
32 operations answer it

idempotency_key_reused422

  • This key was used for a different request.
32 operations answer it

import_already_undone409

  • The import was already undone.
1 operation answer it

import_not_found404

  • No import of yours with that id.
1 operation answer it

import_suggestion409

  • An import suggestion: resolve it instead.
1 operation answer it

internal500

  • Something went wrong on our side (quote the requestId).
182 operations answer it

invalid_addon400

  • The add-on isn’t 2 or 5 digits.
1 operation answer it

invalid_barcode400

  • Not a UPC, EAN or ISBN.
  • The barcode isn’t a UPC, EAN or ISBN.
2 operations answer it

invalid_candidate400

  • The picked candidate doesn’t name a book.
  • The chosen candidate doesn’t name a book.
3 operations answer it

invalid_cert400

  • Cert numbers are 4–64 letters and digits.
  • The slab QR code’s cert number isn’t one.
3 operations answer it

invalid_code400

  • Not a valid barcode, ISBN, ISSN or code (check digits).
  • The code that led here isn’t a valid code.
3 operations answer it

invalid_copy400

  • The copy fields aren’t valid together.
1 operation answer it

invalid_cover_url400

  • The cover isn’t in our covers bucket.
1 operation answer it

invalid_cursor400

  • A list cursor that didn’t come from this route: pass back the nextCursor you were given.

invalid_field400

  • That field can’t be locked.
1 operation answer it

invalid_filter400

  • A filter the route doesn’t allow, or a bad value for one. The detail names what’s allowed.

invalid_idempotency_key400

  • The Idempotency-Key isn’t 1–255 visible ASCII characters.
32 operations answer it

invalid_json400

  • The body isn’t JSON.
76 operations answer it

invalid_listing400

  • The listing’s fields don’t add up (a cert number without a grader…); detail says which.
2 operations answer it

invalid_pending_variant409

  • That pending variant isn’t yours, or isn’t of that issue.
1 operation answer it

invalid_quantity409

  • Hold between 1 and 50 copies, no more than are listed.
1 operation answer it

invalid_record409

  • The conflict has no title to import under.
1 operation answer it

invalid_request400

  • The query or body doesn’t match the schema (see errors[]).
119 operations answer it

invalid_slug400

  • The address isn’t allowed (reserved, too short…).
1 operation answer it

invalid_sort400

  • A sort field the route doesn’t allow.

invalid_state409

  • The hold isn’t in a state that allows this (already answered, closed…).
4 operations answer it

invalid_target409

  • The issue or edition can’t take a copy.
1 operation answer it

invalid_tool400

  • Only proposed changes have previews.
1 operation answer it

invite_closed409

  • It was already answered or withdrawn.
1 operation answer it

invite_expired409

  • It expired.
1 operation answer it

issue_not_found404

  • No issue with that id.
1 operation answer it

known_elsewhere409

  • Another edition has this code.
1 operation answer it

last_owner409

  • A store needs an owner: add another before leaving.
1 operation answer it

listing_unavailable409

  • The book isn’t listed, or not enough copies are left.
4 operations answer it

merge_blocked409

  • The merge can’t run (the details say why).
1 operation answer it

mixed_series400

  • Move issues of one series at a time.
2 operations answer it

moderation_hidden409

  • A moderator hid this listing after a report, so it can’t go back on sale.
1 operation answer it

move_blocked409

  • The move can’t run as asked (the details say why).
1 operation answer it

name_taken409

  • A catalog publisher already has the name.
1 operation answer it

no_barcode400

  • An add-on was sent for a scan without a barcode.
1 operation answer it

no_match409

  • Nothing to add: the scan matched no book.
1 operation answer it

not_assigned409

  • Only a suggestion matched to an edition can be undone.
1 operation answer it

not_available503

  • Undo isn’t available until a database update is applied.
  • Exports aren’t available on this deployment.
2 operations answer it

not_found404

  • Not an admin (moderator): the same 404 as a missing route.
  • Nothing at that address.
  • The issue isn’t in the catalog.
  • That cover isn’t available.
131 operations answer it

not_in_catalog409

  • The picked book isn’t in our catalog yet; search again.
1 operation answer it

not_migrated503

  • The tool needs a database update that hasn’t been applied yet.
  • The database update this needs isn’t applied yet.
7 operations answer it

not_overridden409

  • That field isn’t overridden (any more).
1 operation answer it

nothing_changed400

  • Every value sent is what the record has.
1 operation answer it

own_content400

  • You can’t report your own profile, shop or messages.
1 operation answer it

own_store409

  • The book is in the caller’s own store.
2 operations answer it

owner_role409

  • Owners can only leave on their own.
  • Owners keep the owner role.
2 operations answer it

photo_missing409

  • The photo is gone; decline this one.
  • The photo is gone; approve without it or decline.
2 operations answer it

provider_not_configured409

  • Metron credentials aren’t configured.
1 operation answer it

provisional_exists409

  • A provisional publisher already has the name; adopt it (its id is in the details).
1 operation answer it

question_closed409

  • The question is closed.
2 operations answer it

rate_limited429

  • Too many messages; slow down.
  • Too many previews at once.
  • Signed out: too many requests from your network.
  • Too many requests; wait the Retry-After seconds.
36 operations answer it

repoint_rate_limited409

  • Too many changes today; try again tomorrow.
1 operation answer it

scan_not_found404

  • No scan of yours with that id.
7 operations answer it

self_demotion409

  • Admins can’t remove their own admin access.
1 operation answer it

self_disable409

  • Admins can’t disable their own account.
2 operations answer it

slug_taken409

  • Another store has that address.
1 operation answer it

still_matching409

  • The scan is still being matched; try again shortly.
1 operation answer it

storage_quota409

  • Your photo storage is full.
1 operation answer it

storage_unavailable503

  • Cover storage isn’t set up on this server.
1 operation answer it

store_closed409

  • The store has closed.
4 operations answer it

store_inactive409

  • The store is closed or suspended, so its books can’t be listed for sale.
4 operations answer it

store_limit409

  • The caller already created 5 stores.
1 operation answer it

store_unavailable409

  • The store isn’t taking requests right now.
4 operations answer it

sync_running409

  • A Metron sync is already running.
1 operation answer it

target_is_admin409

  • The account is an admin; remove admin access first.
1 operation answer it

thread_not_found404

  • No such conversation of yours.
2 operations answer it

thread_out_of_date409

  • The conversation changed elsewhere; reload it.
1 operation answer it

too_large413

  • The cover is over 15 MB.
1 operation answer it

too_many_holds409

  • The caller has too many open holds.
1 operation answer it

too_many_invites409

  • Too many open invitations.
1 operation answer it

turn_in_progress429

  • One turn per collector at a time.
1 operation answer it

unauthorized401

  • Not signed in (no session or token, or an expired one).
107 operations answer it

undo_window_passed409

  • Imports can be undone for a limited time only.
1 operation answer it

unreadable422

  • The cover couldn’t be read as an image.
1 operation answer it

unsupported_action400

  • That action doesn’t apply to this kind of report.
1 operation answer it

upload_url_failed502

  • Storage couldn’t sign the upload; try again.
1 operation answer it

version_unavailable409

  • That version can’t be read right now.
1 operation answer it