Errors and Retries

Standard envelope

Newer endpoints return:

{
  "error": "invalid selector",
  "field": "price",
  "detail": "expected identifier",
  "hint": "verify the selector with a parser dry-run"
}

error is always present; the other fields are optional. Older parse/scrape paths can still return plain-text errors in some cases.

Status codes

Status	Meaning	Retry?
400	Malformed JSON/request	No; fix the request
401	Missing, invalid, or inactive key	No; replace the credential
402	Insufficient available credits	After adding credits or releasing reservations
404	Resource absent or not owned	No
413	Legacy HTML upload exceeds 16 MB	No; reduce the upload
422	URL guard, parser/config, sink, batch, SQL, or content validation failed	No; inspect field, detail, and hint
429	RPS, concurrency, pending, or account resource limit	Usually; honor Retry-After when present
502	Target/upstream transport failed	Usually, with backoff
503	Feature not configured or service temporarily unavailable	Retry later unless the feature is disabled

A scrape concurrency rejection is not a generic rate limit. Its structured log/error code is concurrency_limited; wait for the matching fetch or browser slot.

Credit and queue limits

A batch is rejected atomically when credits or pending capacity are insufficient:

{ "error": "insufficient credits", "required": 4980, "available": 3200 }

{ "error": "pending limit", "pending": 24400, "limit": 25000, "accepted": 0 }

No partial batch is accepted. Re-chunk only after capacity becomes available.

LinkedIn codes

LinkedIn endpoints expose stable codes in structured failures:

Code	HTTP	Retryable	Meaning
unsupported_type	422	No	Resource/schema is unsupported
rate_limited	429	Yes	LinkedIn returned 999/429 or an auth wall after internal retries
not_found	404	No	Deleted, private, or nonexistent resource
fetch_failed	502	Yes	Transport or upstream fetch failure
masked_content	success warning	No	Guest fields were masked and returned as null

Failed prebuilt calls do not consume credits. Respect retry_after_seconds when supplied.

Instagram profile availability

instagram-posts can return INSTAGRAM_UPSTREAM_PROFILE_UNAVAILABLE with retryable: true. Branch on code, not message, and do not retry before retry_after_seconds.