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": { "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
| Status | Code | What it means | Retry-After |
|---|---|---|---|
| 401 | invalid_api_key | The API key is missing, malformed or revoked. | |
| 403 | account_suspended | The account is suspended, so none of its keys work. Email support to restore it. | |
| 403 | origin_not_allowed | A browser sent the request from a site that isn't allowed. Call the API from your server. | |
| 404 | not_found | No such path. | |
| 404 | request_not_found | The 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. | |
| 404 | batch_not_found | No batch with that ID belongs to this account. | |
| 405 | method_not_allowed | Wrong method for this route. Searches, jobs and usage use GET. Only /v1/batches takes POST. | |
| 409 | idempotency_conflict | This Idempotency-Key was already used with different search parameters. | |
| 409 | result_not_ready | CSV was requested before every search settled. Poll as JSON until status is complete, then ask for CSV. | 2 |
| 413 | payload_too_large | The batch body is over 256 KB. | |
| 414 | uri_too_long | The query string is longer than 2,048 characters. | |
| 415 | unsupported_media_type | A batch must be sent as Content-Type: application/json. | |
| 422 | unsupported_or_invalid_query | An 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. | |
| 422 | duplicate_parameter | A parameter was sent more than once. | |
| 422 | sort_not_implemented | sort=best_deal is not available. | |
| 422 | invalid_idempotency_key | Idempotency-Key must be 1–128 printable ASCII characters, with no spaces. | |
| 422 | invalid_wait | wait must be a whole number from 0 to 20. | |
| 422 | invalid_body | The batch body is not JSON, or has no searches list. | |
| 422 | batch_too_large | The batch holds more searches than your plan allows at once. pages counts as one search per page. | |
| 422 | invalid_format | format must be json or csv, and include must be results. | |
| 429 | rate_limited | More than 60 API calls this minute for your account. | 60 |
| 429 | quota_exceeded | Your plan's allowance is used up, and you have no extra requests left. | 3600 |
| 429 | too_many_pending | Your account has too many searches still pending. Wait for results before sending more. | 5 |
| 503 | upstream_daily_limit | The marketplace's daily limit was reached, so new searches are paused. Cached results still work. | 86400 |
| 503 | queue_full | The collection queue is full. | 30 |
| 503 | collection_unavailable | We can't collect from this marketplace right now. | 30 |
| 503 | storage_unavailable | Our database is briefly unavailable. | 5 |
| 503 | origin_unavailable | The edge couldn't reach our API server. | 5 |
| 503 | service_unconfigured | The API is misconfigured on our side. Contact support. |
#What to do
- 429: wait
Retry-Afterseconds. Fortoo_many_pending, poll your pending searches with?wait=20until 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_limitcan 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.
| Code | HTTP status | What it means |
|---|---|---|
page_mismatch | 503 | The marketplace repeatedly returned a different page than requested. Retries were exhausted; this search was not charged. |
schema | 503 | The marketplace page changed shape. We fail the job rather than return data we can't trust. |
network | 503 | We couldn't reach the marketplace, or it timed out. |
upstream | 503 | The marketplace returned a server error. |
throttled | 503 | The marketplace rate-limited us. |
blocked | 503 | The marketplace blocked the request. |
rejected | 422 on Poshmark, Mercari, Depop and Whatnot; 503 on eBay | The marketplace rejected the search, for example a cursor it no longer accepts on Poshmark, Mercari, Depop or Whatnot. |
not_found | 404 | The listing doesn't exist or was deleted (OfferUp, Facebook and Vinted item lookups). Not charged. |
filter_not_supported | 422 | The 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_applied | 422 | The 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_served | 422 | Facebook Marketplace has no working city page near this location right now. Try a nearby ZIP code. Not charged. |
auth | 503 | The marketplace didn't accept our session. |
daily_limit | 503 | The marketplace's daily limit was reached. |
deadline_exceeded | 503 | The job didn't finish in time. |
credential_storage | 503 | An 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