Skip to content
rare
⌘K
Marketplace API

Getting started

Errors

The rare.market API error envelope, every error code with its HTTP status, example responses and which errors to retry.

The API uses HTTP status codes. Any response that is not 2xx has a JSON body with one error object.

The error envelope

Response
{
  "error": {
    "code": "not_found",
    "message": "Collection not found"
  }
}
FieldTypeDescription
error.codestringA stable, machine-readable code. Branch on this.
error.messagestringA short sentence for people. It can change; do not parse it.

Error responses carry no Cache-Control header. Do not cache them.

Codes

CodeStatusWhen
bad_request400A parameter or body is invalid: an unknown sort or dir, a malformed cursor, a body that is not JSON, an amount that is not an integer string
unauthorized401A /me route without a valid session token
invalid_api_key401The x-api-key header holds an unknown or revoked key. Leave the header out to call anonymously
limit_reached409Creating a sixth API key for one wallet. Revoke one first
not_found404The resource does not exist, the path is unknown, or a list is missing a required filter
rate_limited429You sent too many requests, per minute or per day. Wait for Retry-After seconds. See Rate limits
too_many_streams429You already hold as many open event streams as your limit allows. Close one first
busy503The API is serving as much outside traffic as it takes at once. Retry after Retry-After seconds; the request did not count
unavailable503The server failed to answer. Retry with backoff

Examples

An unknown collection:

curl
curl "https://rare.market/api/v1/collections/does-not-exist"
Response
{ "error": { "code": "not_found", "message": "Collection not found" } }

A value outside the allowed list:

curl
curl "https://rare.market/api/v1/events?collection=popkins&sort=bogus"
Response
{ "error": { "code": "bad_request", "message": "sort must be time or price" } }

A cursor that was edited or truncated:

curl
curl "https://rare.market/api/v1/collections?cursor=zzz"
Response
{ "error": { "code": "bad_request", "message": "Invalid cursor" } }

A list that needs a filter. GET /orders needs collection or maker, and answers 404 without one:

Response
{ "error": { "code": "not_found", "message": "Pass collection or maker" } }

GET /offers works the same way and needs one of collection, item, maker or receiver.

Analytics endpoints (deals, holder quality, smart money, portfolio and others) answer 404 not_found while their data is not available, for example before the first analytics run for a collection. Treat that as "no data yet", not as a missing collection.

Gas sponsor codes

The gas sponsor routes (POST /sponsor, POST /sponsor/execute, GET /sponsor/status) use the same envelope with codes of their own. See Gas sponsoring.

CodeStatusWhen
bad_request400The body is not JSON, sender is not an address, kind is not base64 transaction kind bytes, or category is unknown
rejected400The network rejected the signed transaction
not_sponsored403The transaction is outside the sponsor policy, or costs or stores too much to sponsor
already_executed409This sponsored transaction was already sent
sponsorship_expired410The sponsorship expired before execution. Request a new one
simulation_failed422The dry run failed, so the transaction would fail on chain
limit_reached429The wallet has used its covered fees
rate_limited429Too many sponsor requests, or a sponsorship from this wallet is still open
budget_exhausted429The daily sponsor budget is used up. Try again the next day
submit_failed502The transaction could not be confirmed. Check the wallet before retrying
sponsor_busy503The sponsor is busy. Retry shortly
sponsor_unavailable503Sponsoring is off or not funded

Handling errors

  • Branch on error.code, not on message.
  • Retry 429 and 503 (and sponsor_busy) with backoff. Do not retry other 4xx codes unchanged: fix the request first.
  • On submit_failed, check whether the transaction landed before you send it again.
# Print the status code after the error body.
curl -sS -w "\n%{http_code}\n" "https://rare.market/api/v1/collections/does-not-exist"
--
TPS:--