Errors

Every Soldgraph API error code, what it means, which ones to retry, and how a failed search job differs from an HTTP error.

Every error has the same JSON body:

Error
{ "error": { "code": "invalid_api_key" } }

Check error.code. error.message says what the code means in plain words, and is safe to show to a user. A 422 for a rejected search can also carry error.param, the name of the input to fix, like cursor or zip. It is there when the fault is one of the route's own inputs. A refused batch carries error.index, the position of the search to fix. A 429 quota_exceeded carries error.upgrade_url, the billing page where you move to a larger plan or buy extra requests. Every response also has an X-Request-Id header. Include it when you contact support. Errors are never charged.

#Error codes

StatusCodeWhat it meansRetry-After
401invalid_api_keyThe API key is missing, malformed or revoked.
403account_suspendedThe account is suspended, so none of its keys work. Email support to restore it.
403origin_not_allowedA browser sent the request from a site that isn't allowed. Call the API from your server.
404not_foundNo such path.
404request_not_foundThe job ID is well-formed but unknown, or belongs to another account. An ID that isn't a UUID is no such path: 404 not_found.
404batch_not_foundNo batch with that ID belongs to this account.
405method_not_allowedWrong method for this route. Searches, jobs and usage use GET. Only /v1/batches takes POST.
409idempotency_conflictThis Idempotency-Key was already used with different search parameters.
409result_not_readyCSV was requested before every search settled. Poll as JSON until status is complete, then ask for CSV.2
413payload_too_largeThe batch body is over 256 KB.
414uri_too_longThe query string is longer than 2,048 characters.
415unsupported_media_typeA batch must be sent as Content-Type: application/json.
422unsupported_or_invalid_queryAn unknown parameter, or a value outside the documented range. error.param names the input to fix when it is one of the route's inputs.
422duplicate_parameterA parameter was sent more than once.
422sort_not_implementedsort=best_deal is not available.
422invalid_idempotency_keyIdempotency-Key must be 1–128 printable ASCII characters, with no spaces.
422invalid_waitwait must be a whole number from 0 to 20.
422invalid_bodyThe batch body is not JSON, or has no searches list.
422batch_too_largeThe batch holds more searches than your plan allows at once. pages counts as one search per page.
422invalid_formatformat must be json or csv, and include must be results.
429rate_limitedMore than 60 API calls this minute for your account.60
429quota_exceededYour plan's allowance is used up, and you have no extra requests left.3600
429too_many_pendingYour account has too many searches still pending. Wait for results before sending more.5
503upstream_daily_limitThe marketplace's daily limit was reached, so new searches are paused. Cached results still work.86400
503queue_fullThe collection queue is full.30
503collection_unavailableWe can't collect from this marketplace right now.30
503storage_unavailableOur database is briefly unavailable.5
503origin_unavailableThe edge couldn't reach our API server.5
503service_unconfiguredThe API is misconfigured on our side. Contact support.

#What to do

  • 429: wait Retry-After seconds. For too_many_pending, poll your pending searches with ?wait=20 until they finish, then send more.
  • Other 4xx errors: fix the key or the request. Sending the same call again won't help.
  • 503: retry with backoff and the same Idempotency-Key. upstream_daily_limit can last a day, so don't keep a request waiting on it.
  • A body with status: "failed": it's a failed job, not an error. See below.

If you keep getting 503s, check the status page.

#Failed job codes

A job can fail after we accept it. A job poll still returns HTTP 200, with status: "failed" and one of these codes in error.code. Failed jobs cost nothing.

The HTTP status column is what a search call returns when its job has already failed, and what your dashboard logs show. A 4xx means the search itself caused the failure, like a filter the marketplace ignored or a deleted listing: change the search before you send it again. A 503 means the failure was on our side or the marketplace's, and the same search can work later.

CodeHTTP statusWhat it means
page_mismatch503The marketplace repeatedly returned a different page than requested. Retries were exhausted; this search was not charged.
schema503The marketplace page changed shape. We fail the job rather than return data we can't trust.
network503We couldn't reach the marketplace, or it timed out.
upstream503The marketplace returned a server error.
throttled503The marketplace rate-limited us.
blocked503The marketplace blocked the request.
rejected422 on Poshmark, Mercari, Depop and Whatnot; 503 on eBayThe marketplace rejected the search, for example a cursor it no longer accepts on Poshmark, Mercari, Depop or Whatnot.
not_found404The listing doesn't exist or was deleted (OfferUp, Facebook and Vinted item lookups). Not charged.
filter_not_supported422The marketplace doesn't offer a filter you sent for this kind of search, such as vehicle filters on a non-vehicle OfferUp search. Not charged.
filter_not_applied422The marketplace returned results that don't match a filter you sent, so we don't return them. Change or drop that filter and search again. Not charged.
location_not_served422Facebook Marketplace has no working city page near this location right now. Try a nearby ZIP code. Not charged.
auth503The marketplace didn't accept our session.
daily_limit503The marketplace's daily limit was reached.
deadline_exceeded503The job didn't finish in time.
credential_storage503An internal error on our side.

Retrying a failed search with the same Idempotency-Key returns the failed job again, with the status in the table. To try again, send it with a new key.

Overviews: eBay sold listings API · findCompletedItems alternative · Poshmark sold listings API · Mercari sold listings API · Pokémon card price API · Sold comps API for reseller apps