Skip to main content

​
Error shape

Every error response is JSON with at least: 
{
  "error": "insufficient_credits",
  "message": "Not enough credits for this request",
  "request_id": "b3f1c2...",
  "credits_remaining": 0
}
  • error — a short machine-readable code (see table below).
  • message — a human-readable description.
  • request_id — unique per call; include this if you contact support about a specific request.
  • credits_remaining — present on most errors that occur after authentication, so you can tell your balance without a separate /v1/usage call. Absent on errors that happen before your key is even charged (e.g. bad auth, bad request body).
A 422 (“no result found”) response additionally includes credits_charged, since some endpoints still charge on a clean miss — see Credits & Pricing. In the rare case a compensating refund itself fails, you may also see "refund_issue": true — this means the charge may not have been refunded yet; contact support with the request_id and it’ll be reconciled.

​
Status codes

StatuserrorMeaning
400invalid_requestRequest body failed validation (missing/malformed fields). Nothing was charged.
401unauthorizedMissing Authorization header, or the key is invalid/revoked.
402insufficient_creditsYour balance is too low for this call’s price. The vendor is never called.
422not_foundThe vendor was called successfully but found no result. May still be charged — see above.
429rate_limitedYou’ve exceeded the rate limit (below). Nothing was charged.
502vendor_errorThe upstream data vendor errored or timed out. Any reserved credits are refunded in full.
503vendor_capacityThis endpoint is temporarily unavailable due to a vendor capacity limit. Nothing was charged; retry later.
A 200 response is always success — a real payload with a normal charge, or in a couple of specific cases (see the “charged on success only” endpoint in Credits & Pricing) a payload with credits_charged: 0.

​
Rate limit

60 requests per minute per API key, enforced with a fixed one-minute window. Going over returns 429 before any credits are touched or any vendor is called. There’s no separate burst allowance today — spread out high-volume workloads across the minute rather than bursting.