0xDocs 0x.limo

Docs / REST API

Errors

The error format, what each HTTP status means on the 0x API, the error strings you will meet and when to retry.

Every error is JSON with the HTTP status:

json
{"error": "no such site of yours"}

Some errors carry more fields. A 422 from hosting lists problems, a 409 lists missing, a 429 has retry_after_ms, and a payment error names what is short. The OAuth routes answer in the RFC 6749 form {"error": "<code>", "error_description": "..."} (see token endpoint errors).

error is a short English sentence or a snake_case code. Codes are stable: match on them. A sentence may be reworded, so show it to the developer or the player, but don't parse it.

#Statuses

StatusMeaning on 0xWhat to do
200 / 201Done (201: something new was created: a site, an order, a top-up, a plan)
206Partial content for a Range request (trailers, web seeds)
302Redirect (sign-in pages, store sign-in links)follow it
400The request is malformed: a bad ID, a missing field, text with NUL or invalid charactersfix the request
401No token, or the token is invalid, expired or revokedrefresh the token, or sign in again
402The game must be bought first (not_owned, with its price)send the player to the store
403Signed in, but not allowed: not the owner, a guest where an account is needed (account_required), a feature closed for this accountdon't retry
404No such thing or a feature that is off ("in-game purchases are off", "subscriptions are off")check the ID; check the feature's status
405Wrong method for the path
409A conflict with the current state: a name taken, already owned, files still to upload, insufficient fundsread the body; it says what conflicts
410Gone: a purchase request that expiredstart again
413Too large: over the hosting quota, too many files, a file over the limit
415Unsupported media type (trailers are MP4 or WebM)
416The Range can't be satisfied
422The content was refused: a hosted version's file list, or the site builder's findingsfix the files listed in problems / findings
429Rate limitedwait Retry-After seconds (Rate limits)
451Content blocked by moderation, or refused by the upload scanner
500An internal error (the details are logged on our side, not sent)retry with backoff; report it if it persists
502The payment checkout failed upstream (checkout_failed)retry later
503A dependency is briefly unavailable (temporarily unavailable), the node is draining, or a feature isn't configured (play_tickets_closed)retry with backoff

#Retrying

  • GET requests are always safe to retry.
  • Writes are safe to retry only when they carry an idempotency key. Use the Idempotency-Key header or the idempotency_key field (see Idempotency). A retried purchase with the same key returns the first result instead of charging again.
  • On 429, wait at least Retry-After seconds; don't hammer.
  • On 500, 502 and 503, back off exponentially (for example 0.5 s, 1 s, 2 s, 4 s, then give up). The API already retries idempotent requests internally during a database failover, which takes about 8 seconds, before it answers 503.
  • Never retry 400, 401 (refresh first), 403, 404, 409 or 422 unchanged.

#Common error strings

These are the errors developers meet most. The full set for each route is in the generated reference.

errorStatusWhere
invalid or expired token401any authenticated route
invalid or revoked publish token401/v1/listings* with a 0xpub_ token
account_required403guests writing reviews, votes, purchases
bad app id / bad appid / appid required400{appid} that isn't a number
bad steamid400a {steamid} that isn't a 64-bit decimal
bad idempotency key400an Idempotency-Key that is empty, longer than 256 or not printable ASCII
text with NUL or invalid characters400any text field
no such app / no such world / no such game in the store404an unknown or unlisted appid
no such site / no such site of yours404hosting: unknown site, or not yours
no such version / bad version404 / 400hosting versions
that site name is taken / that site name is reserved409POST /v1/hosting/sites
at most 20 sites per developer403POST /v1/hosting/sites
upload refused (+ problems)422POST /v1/hosting/sites/{site}/versions
files still to upload (+ missing)409finalize before every blob is uploaded
the site builder refused this version (+ findings)422finalize
over your hosting quota (...)413opening a version past 2048 MiB
no such lobby404lobbies
only the owner sets lobby data / not a member403lobbies
no licence for this app403POST /v1/auth/tickets
not_owned402play tickets for a paid game
already_owned / not_for_sale409store orders
insufficient_funds (+ missing, missingUsd)409wallet payments, purchases, subscriptions
network_unavailable409a top-up on a network the checkout has paused
checkout_failed502a top-up the checkout couldn't open
payments are off / in-game purchases are off / subscriptions are off404a feature switched off on this service
content blocked451swarm tracker: content an operator blocked
rate limited (+ retry_after_ms)429everywhere
temporarily unavailable503a dependency is down; retry