Response Codes

Every Ziptax response carries an application-level response code in addition to the HTTP status. The code tells you what happened in business terms (success, bad input, plan-gated feature, quota exhausted, and so on) and is the signal your integration should branch on.

Response envelope

Both success and error responses use the same envelope. The code lives at metadata.response:

1
{
2
  "metadata": {
3
    "version": "v60",
4
    "response": {
5
      "code": 100,
6
      "name": "RESPONSE_CODE_SUCCESS",
7
      "message": "Successful API Request.",
8
      "definition": "http://api.zip-tax.com/request/v60/schema"
9
    }
10
  }
11
}

Full list

When you’ll see each

100, Success

The lookup completed and the response contains rate data. Always check for 100 before reading baseRates or taxSummaries.

101, Invalid key

The X-API-Key header (or key= query parameter) is missing, malformed, or doesn’t match a key in our database. Check for trailing whitespace, encoding issues, or using the wrong environment’s key.

102 to 105, Input validation

The state, city, postal code, or overall query string isn’t in a shape Ziptax can parse. These are deterministic, so re-sending the same request will always fail the same way. Fix the input before retrying.

106, Unknown API error

Something went wrong on our end. Safe to retry with exponential backoff. If you see these persistently, email support@zip.tax.

107, Feature not enabled

The API version or feature you requested isn’t available on your plan (for example, calling /request/v60 on a plan that only includes v40). Upgrade your plan or use a supported version.

108, Rate limit

You’ve sent more requests than your per-minute request_rate entitlement allows within the current 60-second sliding window. The response includes X-RateLimit-Limit and X-RateLimit-Remaining headers. See Rate Limiting & Errors for backoff guidance.

109, Address incomplete

The address (or lat/lng, or postal code) you sent couldn’t be resolved to a real location. Common causes: missing street number, obviously wrong ZIP for the city, coordinates in the middle of the ocean, or a typo that leaves the geocoder unable to disambiguate.

110, No result

Parameters were valid but nothing matched. Most common on historical lookups where the date precedes our coverage, or niche international territories.

111, Invalid historical

The historical parameter isn’t a parseable ISO-8601 date. Use the format YYYY-MM-DD (e.g. 2024-01-15).

112, International not enabled

You passed countryCode=CAN (or another non-USA country) but your account doesn’t have the rate_loc_can entitlement. Upgrade to Pro or Enterprise to unlock Canadian lookups.

113, Product rules not enabled

You passed taxabilityCode=... but your account doesn’t have the product_rates entitlement. Upgrade to Pro or Enterprise to unlock product-specific rate rules. See Taxability Information Codes for what this parameter does.

Handling codes programmatically

Branch on the numeric code, not the HTTP status or message text. The messages are documented here for humans but may be refined over time. The codes are stable.

1
import requests
2
3
res = requests.get(
4
    "https://api.zip-tax.com/request/v60",
5
    headers={"X-API-Key": "YOUR_API_KEY"},
6
    params={"address": "200 Spectrum Center Dr, Irvine CA"},
7
)
8
data = res.json()
9
code = data["metadata"]["response"]["code"]
10
11
if code == 100:
12
    rate = data["taxSummaries"][0]["rate"]
13
elif code == 108:
14
    # back off, respect X-RateLimit-* headers
15
    ...
16
elif code in (112, 113):
17
    # feature not on this plan; show an upsell or skip silently
18
    ...
19
elif code == 109:
20
    # address didn't resolve; prompt the user to fix it
21
    ...
22
else:
23
    # log, alert, and fail closed
24
    ...

Retry guidance at a glance

Related