Error Response Format
Every Fetchin API error returns the same JSON shape: a human-readableerror string and a stable, machine-readable code. Branch your integration
on code (and the HTTP status) — never on the error text, which may change.
details object (or, for the multi-profile
endpoint, top-level fields such as creditsNeeded) with extra context.
Authentication errors (
401, 403) additionally include legacy message and
statusCode fields for backward compatibility. New integrations should rely on
error and code.Error Code Reference
HTTP Status Codes
400 Bad Request
The request itself is malformed — a missing parameter (MISSING_PARAMETER), an
invalid value (INVALID_PARAMETER), or an unparseable professional URL/URN
(INVALID_URN).
401 Unauthorized
TheX-API-Key header is missing (UNAUTHENTICATED) or invalid
(INVALID_API_KEY).
404 Not Found
We reached the service successfully, but the requested profile, post, or company genuinely does not exist.402 Payment Required
You ran out of monthly credits (code: "QUOTA_EXHAUSTED"). There is no
Retry-After — waiting does not help; upgrade your plan or wait for your
renewal date.
429 Too Many Requests
You exceeded your per-second request rate (code: "RATE_LIMITED"). A
Retry-After header tells you how long to wait.
Retry-After.
503 Service Unavailable
Our API is temporarily unable to serve your request — we’re at capacity or overloaded. This is on our side. It is not your request’s fault and not an upstream service outage.Retry-After header.
The same request will typically succeed shortly after.
500 Internal Server Error
An unexpected bug occurred in our API.502 / 504 Upstream Errors
UPSTREAM_ERROR (502) and UPSTREAM_TIMEOUT (504) indicate a genuine failure or
timeout on the upstream service’s side (as opposed to our capacity, which is 503). Retry
with backoff.
Error Handling Examples
JavaScript/TypeScript
Python
Best Practices
Branch on `code`, not the message
Branch on `code`, not the message
The
error string is for humans and may change. The code is a stable
contract — switch on it to decide how to react.Retry 503, 500, and 429 — but not 4xx
Retry 503, 500, and 429 — but not 4xx
503, 500, 429, 502, and 504 are transient and safe to retry with
exponential backoff. A 400/401/404 will keep failing until you change
the request.Honor Retry-After
Honor Retry-After
429 and 503 responses include a Retry-After header (seconds). Wait at
least that long before retrying.Distinguish RATE_LIMITED from QUOTA_EXHAUSTED
Distinguish RATE_LIMITED from QUOTA_EXHAUSTED
They now have different HTTP statuses:
QUOTA_EXHAUSTED is 402 (you need
more credits — upgrade or wait for renewal), RATE_LIMITED is 429 (slow
down and honor Retry-After). The code field carries the same
distinction. They require different handling.Treat 503 as 'try again', not 'no data'
Treat 503 as 'try again', not 'no data'
503 SERVICE_UNAVAILABLE means we couldn’t serve you right now — it does not
mean the profile/post is empty or gone. Retry shortly.Quota & Credits
Failed requests (any4xx/5xx) do not consume credits. See
Quotas and Rate Limits for details.