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.

HTTP 404
{
  "detail": {
    "error": "company_not_found",
    "message": "No Trustpilot profile found for 'example-shop.com'"
  }
}

Error codes

HTTPerrorMeaningWhat to do
400invalid_parameterA 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.
401missing_api_keyNo API key in X-API-Key or Authorization: Bearer.Send your key in one of the two headers.
401invalid_api_keyThe key does not exist or has been revoked.Check the key or create a new one in the dashboard.
402insufficient_creditsYour credit balance is 0.Buy a credit pack or wait for the monthly free credits.
404company_not_foundNo company page exists for this domain.Check the domain, or find the company with /v1/companies/search.
404category_not_foundThe category id does not exist.Get valid ids from /v1/categories.
422invalid_cursorThe 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.
429rate_limit_exceededToo many requests per minute.Wait for the seconds in the Retry-After header, then retry.
429insufficient_credits_retry_laterThe balance ran out on recent calls and the key is cooling down.Top up your credits; Retry-After says when to try again.
502upstream_changedTrustpilot 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.
503upstream_blockedTrustpilot is temporarily blocking requests.Retry with exponential backoff.
503upstream_errorTrustpilot is unreachable or returned an error.Retry with exponential backoff.
504upstream_timeoutTrustpilot did not answer in time.Retry; for reviews, a smaller limit answers faster.
500internal_errorUnexpected 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}")

Next Steps