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:
{"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
| Status | Meaning on 0x | What to do |
|---|---|---|
200 / 201 | Done (201: something new was created: a site, an order, a top-up, a plan) | |
206 | Partial content for a Range request (trailers, web seeds) | |
302 | Redirect (sign-in pages, store sign-in links) | follow it |
400 | The request is malformed: a bad ID, a missing field, text with NUL or invalid characters | fix the request |
401 | No token, or the token is invalid, expired or revoked | refresh the token, or sign in again |
402 | The game must be bought first (not_owned, with its price) | send the player to the store |
403 | Signed in, but not allowed: not the owner, a guest where an account is needed (account_required), a feature closed for this account | don't retry |
404 | No such thing or a feature that is off ("in-game purchases are off", "subscriptions are off") | check the ID; check the feature's status |
405 | Wrong method for the path | |
409 | A conflict with the current state: a name taken, already owned, files still to upload, insufficient funds | read the body; it says what conflicts |
410 | Gone: a purchase request that expired | start again |
413 | Too large: over the hosting quota, too many files, a file over the limit | |
415 | Unsupported media type (trailers are MP4 or WebM) | |
416 | The Range can't be satisfied | |
422 | The content was refused: a hosted version's file list, or the site builder's findings | fix the files listed in problems / findings |
429 | Rate limited | wait Retry-After seconds (Rate limits) |
451 | Content blocked by moderation, or refused by the upload scanner | |
500 | An internal error (the details are logged on our side, not sent) | retry with backoff; report it if it persists |
502 | The payment checkout failed upstream (checkout_failed) | retry later |
503 | A 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-Keyheader or theidempotency_keyfield (see Idempotency). A retried purchase with the same key returns the first result instead of charging again. - On
429, wait at leastRetry-Afterseconds; don't hammer. - On
500,502and503, 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 answers503. - Never retry
400,401(refresh first),403,404,409or422unchanged.
#Common error strings
These are the errors developers meet most. The full set for each route is in the generated reference.
error | Status | Where |
|---|---|---|
invalid or expired token | 401 | any authenticated route |
invalid or revoked publish token | 401 | /v1/listings* with a 0xpub_ token |
account_required | 403 | guests writing reviews, votes, purchases |
bad app id / bad appid / appid required | 400 | {appid} that isn't a number |
bad steamid | 400 | a {steamid} that isn't a 64-bit decimal |
bad idempotency key | 400 | an Idempotency-Key that is empty, longer than 256 or not printable ASCII |
text with NUL or invalid characters | 400 | any text field |
no such app / no such world / no such game in the store | 404 | an unknown or unlisted appid |
no such site / no such site of yours | 404 | hosting: unknown site, or not yours |
no such version / bad version | 404 / 400 | hosting versions |
that site name is taken / that site name is reserved | 409 | POST /v1/hosting/sites |
at most 20 sites per developer | 403 | POST /v1/hosting/sites |
upload refused (+ problems) | 422 | POST /v1/hosting/sites/{site}/versions |
files still to upload (+ missing) | 409 | finalize before every blob is uploaded |
the site builder refused this version (+ findings) | 422 | finalize |
over your hosting quota (...) | 413 | opening a version past 2048 MiB |
no such lobby | 404 | lobbies |
only the owner sets lobby data / not a member | 403 | lobbies |
no licence for this app | 403 | POST /v1/auth/tickets |
not_owned | 402 | play tickets for a paid game |
already_owned / not_for_sale | 409 | store orders |
insufficient_funds (+ missing, missingUsd) | 409 | wallet payments, purchases, subscriptions |
network_unavailable | 409 | a top-up on a network the checkout has paused |
checkout_failed | 502 | a top-up the checkout couldn't open |
payments are off / in-game purchases are off / subscriptions are off | 404 | a feature switched off on this service |
content blocked | 451 | swarm tracker: content an operator blocked |
rate limited (+ retry_after_ms) | 429 | everywhere |
temporarily unavailable | 503 | a dependency is down; retry |
