Errors

Every non-2xx response has the same body:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Balance is 3 credits but this request costs 5. Top up at extractr.dev/dashboard/billing."
  }
}

code — a stable, machine-readable string. Branch on this.
message — human-readable detail. May change; don't parse it.
reason — present on some 404 not_found responses, when the provider can tell why the resource is gone. Stable; safe to branch on.

Failed requests are never charged.

Why a listing is gone

Marketplace listing endpoints (e.g. /vinted/get_listing) set reason on a 404:

`reason`	Meaning	Worth re-checking?
`sold`	The item sold.	No
`removed`	Deleted by the seller or the marketplace.	No
`seller_on_holiday`	Hidden while the seller is away; it comes back when they return.	Yes, occasionally
`unavailable`	The listing exists but the marketplace isn't showing it and doesn't say why (hidden, under review, or recently sold).	Yes, occasionally

404 not_found (sold)

{
  "error": {
    "code": "not_found",
    "message": "Vinted listing 10005094745 has been sold",
    "reason": "sold"
  }
}

Error codes

Status	Code	When
401	`unauthorized`	No API key (or session token) supplied.
401	`invalid_api_key`	Key malformed, unknown or revoked.
402	`insufficient_credits`	Balance below the endpoint's cost. Top up or enable auto top-up.
403	`insufficient_scope`	The key is valid but not scoped for this provider.
404	`not_found`	Unknown route, or the requested resource doesn't exist.
422	`validation_error`	A query/path/body parameter is missing or malformed.
429	`rate_limited`	Too many requests — back off and retry after `Retry-After`.
502	`upstream_error`	The upstream source is temporarily unavailable. Retry; no credits were charged.
400	`stripe_not_configured`	Billing action attempted while Stripe isn't configured (self-hosted/dev).
503	`service_unavailable`	We are briefly unable to serve requests (e.g. our database is restarting). Retry after `Retry-After`.
500	`internal_error`	Something failed on our side. Safe to retry.

Examples

401 invalid_api_key

{
  "error": {
    "code": "invalid_api_key",
    "message": "API key is revoked or does not exist."
  }
}

422 validation_error

{
  "error": {
    "code": "validation_error",
    "message": "Query parameter \"symbol\" is required."
  }
}

429 rate_limited

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry after a short backoff."
  }
}

Handling errors

Treat 429, 500, 502 and 503 as retryable (with exponential backoff); treat 401, 402, 403 and 422 as bugs or billing state to surface immediately:

const res = await fetch(url, { headers: { "X-API-Key": key } });
if (!res.ok) {
  const { error } = await res.json();
  switch (error.code) {
    case "insufficient_credits":
      // alert billing / trigger a top-up
      break;
    case "rate_limited":
    case "internal_error":
    case "upstream_error":
    case "service_unavailable":
      // retry with backoff
      break;
    default:
      throw new Error(`${error.code}: ${error.message}`);
  }
}

Every response from a data endpoint carries an X-Request-Id header. It is the id of that call in your usage log: open Dashboard → Usage and click the row (or search the CSV export's request_id column) to see the exact query parameters and request body you sent, the response you received, and the error code and message for a failed call. Quote it when you contact support.

Bodies are stored truncated (the first 16 KB of a request and 64 KB of a response); the original size is shown so you can tell when a payload was cut.

Why a listing is gone

Error codes

Examples

Handling errors

Request IDs

On this page