Error Handling
Every error has the same JSON body, a stable error code and an HTTP status. Failed calls cost 0 credits.
Error response format
Branch on detail.error (machine-readable, stable); show detail.message to humans.
{
"detail": {
"error": "company_not_found",
"message": "No Trustpilot profile found for 'example-shop.com'"
}
}Error codes
| HTTP | error | Meaning | What to do |
|---|---|---|---|
| 400 | invalid_parameter | A parameter is invalid: bad domain, stars, language or date, missing query, limit out of range... | Fix the request; the message names the parameter. Do not retry unchanged. |
| 401 | missing_api_key | No API key in X-API-Key or Authorization: Bearer. | Send your key in one of the two headers. |
| 401 | invalid_api_key | The key does not exist or has been revoked. | Check the key or create a new one in the dashboard. |
| 402 | insufficient_credits | Your credit balance is 0. | Buy a credit pack or wait for the monthly free credits. |
| 404 | company_not_found | No company page exists for this domain. | Check the domain, or find the company with /v1/companies/search. |
| 404 | category_not_found | The category id does not exist. | Get valid ids from /v1/categories. |
| 422 | invalid_cursor | The cursor is malformed, tampered with, or was created for other filters. | Pass meta.next_cursor unchanged, with the same filters as the request that returned it. |
| 429 | rate_limit_exceeded | Too many requests per minute. | Wait for the seconds in the Retry-After header, then retry. |
| 429 | insufficient_credits_retry_later | The balance ran out on recent calls and the key is cooling down. | Top up your credits; Retry-After says when to try again. |
| 502 | upstream_changed | Trustpilot changed its page format and the response could not be read. | Do not retry in a loop; we are notified and fix it. Try again later. |
| 503 | upstream_blocked | Trustpilot is temporarily blocking requests. | Retry with exponential backoff. |
| 503 | upstream_error | Trustpilot is unreachable or returned an error. | Retry with exponential backoff. |
| 504 | upstream_timeout | Trustpilot did not answer in time. | Retry; for reviews, a smaller limit answers faster. |
| 500 | internal_error | Unexpected error on our side. | Retry later; contact support if it persists. |
Credits and retries
Failed calls are free
Only successful responses are billed. Any 4xx or 5xx response costs 0 credits, so retrying a failed call never charges you twice.
Retry-After on 429
Both 429 codes set the Retry-After header (seconds). Wait that long before the next request. For insufficient_credits_retry_later, waiting alone does not help: top up your balance first.
Which errors to retry: 429 rate_limit_exceeded (after Retry-After), 503, 504 and 500 (exponential backoff). Do not retry 400, 401, 402, 404, 422 without changing the request, and do not retry 502 upstream_changed in a loop.
Handling errors in code
The SDKs raise a typed error for each family of codes and retry 429/5xx automatically (respecting Retry-After). Every error extends ScrapeReviews and exposes status_code, code and retry_after.
from scrapereviews import (
ScrapeReviews,
ScrapeReviews,
InsufficientCreditsError,
InvalidParameterError,
NotFoundError,
RateLimitError,
)
client = ScrapeReviews() # reads SCRAPEREVIEWS_API_KEY
try:
company = client.companies.get("example-shop.com")
except NotFoundError as e:
print("No such company:", e.code) # company_not_found
except InvalidParameterError as e:
print("Bad request:", e.message)
except InsufficientCreditsError:
print("Out of credits: buy a pack in the dashboard")
except RateLimitError as e:
print(f"Slow down, retry in {e.retry_after}s")
except ScrapeReviews as e:
print(f"API error {e.status_code} {e.code}: {e.message}")