API v2 Errors
API v2 uses structured problem responses with stable error codes, request IDs, and clear credit charging rules.
Error catalog
API v2 errors are returned as application/problem+json. Domain misses are a soft result: 200 with found: false, so no-code workflows can continue row by row.
| Code | HTTP | Title | Retry | Charged | Meaning |
|---|---|---|---|---|---|
| invalid_api_key | 401 | Invalid API key | no | no | Provide a valid API key using the Authorization: Bearer header. |
| invalid_field | 400 | Invalid include | no | no | One or more requested fields do not exist. |
| upgrade_required | 403 | Upgrade required | no | no | One or more requested fields are not available on the current plan. |
| insufficient_credits | 403 | Insufficient credits | no | no | This request requires more credits than are currently available. |
| domain_not_found | 200 | Domain not found | no | no | Domain lookup returns found=false and does not spend credits when no ShopRank record is found. |
| rate_limited | 429 | Rate limited | yes | no | Too many requests were sent in a short time window. Retry after the period returned by the API. |
Example error
{
"type": "https://shoprank.com/problems/upgrade_required",
"title": "Upgrade required",
"status": 403,
"detail": "One or more requested fields are not available on the current plan.",
"code": "upgrade_required",
"request_id": "01f3b41a-0ff6-4e0e-94d3-06a8e19d9892",
"current_plan": "standard",
"required_plan": "enterprise",
"locked_fields": [
{
"field": "merchant_size_score",
"required_plan": "enterprise"
}
],
"locked_features": [
{
"field": "merchant_size_score",
"label": "Merchant size score",
"required_package": "Enterprise"
}
],
"upgrade_url": "https://shoprank.com/contact?ref=api-v2-upgrade-required"
}Raw error catalog JSON is available at /api/v2/errors.