Skip to content

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>
Unfortunately, this response is provided by CloudFront, and is not JSON formatted. If your workflow involves requesting many 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"
}
Very large requests (high 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= as gsheet or csv 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.