Response
Response Status Codes¶
Code | Description |
---|---|
200 | Success |
202 | Success - output will be written to a file (link provided) |
402 | Payment Required - please purchase more SourceStack credits |
403 | Forbidden - please set your API key as the X-API-KEY header |
413 /414 | Query url parameter value is too long |
422 | Query malformed - please check your parameters and their values |
429 | Rate Limited - please contact your account representative |
500 | SourceStack server error |
504 | Request timed out (> 30 seconds) |
Response Keys¶
Name | Presence | Sample Value |
---|---|---|
entry_count | 200 or 202 code | 1 |
message | 200, 202, 402, 422, or 500 code | "No Rows Found" |
data | 200 code | [{"company_name": "Shopify","product_name": "Shopify Plus","categories": "eCom, Cart","url": "shopify.com/plus"}] |
link | 202 code | "https://docs.google.com/spreadsheets/d/foobar" |
X-SOURCESTACK-CREDITS-REMAINING header | 200, 202, or 422 code | 7829 |
X-SOURCESTACK-REQUEST-ID header | 200, 202, or 422 code | 3278f76e437af00764b857df5c20938sag |
Successful Responses¶
200 code
- success¶
GET /products?name=Shopify Plus&exact=True&fields=company_name,product_name,categories,company_url
{
"entry_count": 1,
"message": "Success",
"data": [
{
"company_name": "Shopify",
"product_name": "Shopify Plus",
"categories": "eCom, Cart",
"product_url": "shopify.com/plus"
}
]
}
200 code
- successfully found 0 rows¶
GET /companies?name=extremelyspecificthingthatdoesntexist&exact=True
{
"entry_count": 0,
"message": "No Rows Found",
"data": []
}
202 code
- alternate export
specified¶
GET /companies?category=Education&export=gsheet
{
"entry_count": 10,
"message": "Your GSheet will be written to shortly. You can retrieve your file at the provided link ",
"link": "https://docs.google.com/spreadsheets/d/1KjdC5a_VtV7R7DXdt3vOTHo7BXxDd2tHxCD4kFl4UeM"
}
202 code
- service limit fallback (see below)¶
GET /companies?uses_product=Shopify&limit=31000
{
"entry_count": 31000,
"message": "The output was too large to write to return via API. It was, however, successfully written to CSV. You can retrieve your file at the provided link ",
"link": "https://sourcestackpublicresultsbucket.s3-us-west-2.amazonaws.com/dq9zf1pds092japvi67m.csv"
}
Unsuccessful Responses¶
All unsuccessful requests (status_code >400) do not have any credit cost.
402 code
- not enough SourceStack credits¶
GET /companies?name=foo&limit=50000
{
"message": "Your request includes a higher limit: 50000 than you have credits remaining: 10000. Please purchase more credits or reduce the limit requested"
}
403 code
- forgot to add SourceStack API key as X-API-KEY
header¶
GET /companies?name=foo
{
"message": "Forbidden"
}
413
and 414 code
- request URLs querystrings are too large (>8192 bytes cumulatively, ~7200 characters of urls)¶
GET /companies?urls=domain1.com,domain2.com,domain1000.com,domain1001.com,etc,etc
<H1>413 ERROR</H1>
<H2>The request could not be satisfied.</H2>
urls
, make sure your response handling logic checks the status code before accessing the response JSON. 422 code
- missing a search_param¶
GET /companies
{
"message":"You must provide at least one search param (and associated value). Acceptable search params: ['name', 'url', 'category', 'parent', 'uses_product', 'uses_category', 'filters']"
}
422 code
- missing value for search param¶
GET /companies?name
{
"message":"You must provide a value with your search param(s): ['name']"
}
422 code
- more than one search param¶
GET /companies?name=store&filters=[{"field":"tags_matched","operator":"CONTAINS","value":"Shopify"}]
{
"message":"You must provide only one search parameter. If you wish to combine multiple query criteria, use Advanced Filtering (sourcestack.co/filtering). You provided: ['Name', 'Filters']"
}
422 code
- endpoint does not support this search_param¶
GET /skus?uses_product=baz
{
"message":"The search_parameter you provided is not supported on this endpoint"
}
422 code
- endpoint does not support this fields
value¶
GET /jobs?name=engineer&fields=spaghetti
{
"message": "This dataset does not support the following 1 provided Fields value(s): ['spaghetti']. A list of accepted field values can be found in the Docs."
}
422 code
- fields
value contains duplicates¶
GET /skus?name=engineer&fields=sku_url,company_name,sku_url
{
"message": "Your value for 'fields' includes duplicates - ['sku_url']. Please remove the duplicate entry(s) and try again"
}
422 code
- Advanced Filtering field is not compatible with provided operator (More Here)¶
POST /companies?filters=[{"field":"categories","operator":"GREATER_THAN","value":5}]
{
"message": "Your filter used an unsupported combination of 'field' and 'operator': categories and GREATER_THAN"
}
422 code
- POST request does not include Content-Type=application/json
header¶
POST /companies
{
"message": "The request 'body' provided is malformed. Ensure it is valid JSON, has an appropriate Content-Type header, and contains at least one of: ['name', 'url', 'category', 'parent', 'uses_product', 'uses_category', 'filters']"
}
422 code
- One Max_Per parameter is missing¶
GET /companies?max_per_field=country
{
"message": "Max_Per_Limit and Max_Per_Field must both be present together in a request. Your query included only ['Max_Per_Field']"
}
422 code
- Max_Per_Field is not a supported field¶
GET /companies?max_per_field=countries&max_per_limit=5
{
"message": "The value for Max_Per_Field must be a supported field. Your input was: ['countries']. Did you mean ['country'] ? A list of accepted field values can be found in the Docs."
}
422 code
- Max_Per combined with Count_Only¶
GET /companies?max_per_field=country&max_per_limit=5&count_only=true
{
"message": "Max_Per in combination with Count_Only is not currently supported."
}
429 code
- rate limited (More Here)¶
500 or 502 code
- serverside error¶
{
"message": "Internal server error"
}
504 code
- request timed out¶
{
"message": "Endpoint request timed out"
}
limit
+ numerous fields
set) may exceed the API call timeout window (30 seconds) Response Service Limits¶
The various export
options of the SourceStack API have associated service limits:
export Type | Limit per Request |
---|---|
airtable | 1,200 entries |
caller or None | 20,000 entries |
gsheet | 100,000 entries |
xml | 100,000 entries |
csv | 500,000 entries |
If they are exceeded, the API will try to salvage the output, and will write to csv
instead.
In that case, the statusCode
will be 202 and the message
will be one of:
The output was too large to return via API. It was, however, successfully written to S3. You can retrieve your file at the provided link
The output was too large to write to GSheet. It was, however, successfully written to S3. You can retrieve your file at the provided link
To minimize the complexity of your response handling logic, we recommend you:
- control the maximum number of returned rows with the
limit=
param - minimize
fields=
values to only those data fields needed - set
export=
asgsheet
orcsv
preemptively for larger requests
Response Rate Limiting¶
Rate Limit | Limits at |
---|---|
burst | 20 requests per ~2 second burst |
throughput | 10 requests/second on average |
daily | 1000 requests/day |
To ensure API stability, requests are subject to average throughput, burst, and daily limits.
Requests above a given rate limit will respond with status code 429
until the period elapses.
If you are concerned the rate limits may block your use case, speak with your account representative about how to schedule and batch your requests.