Skip to main content

Error Response Format

Every Fetchin API error returns the same JSON shape: a human-readable error string and a stable, machine-readable code. Branch your integration on code (and the HTTP status) — never on the error text, which may change.
Some errors include an optional 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).
Solution: Fix the request. Retrying without changes will fail again.

401 Unauthorized

The X-API-Key header is missing (UNAUTHENTICATED) or invalid (INVALID_API_KEY).
Solution: Include a valid API key from your dashboard.
A sudden INVALID_API_KEY on a previously working integration usually means the key was revoked from the dashboard. A revoked key never comes back — create a new one, deploy it, and check the Last used column before revoking anything else. See Rotating your API key.

404 Not Found

We reached the service successfully, but the requested profile, post, or company genuinely does not exist.
Solution: Don’t retry — verify the URL/URN you sent.
A 404 consumes 1 credit. It is the one failing response that does, and it is the more expensive answer to produce rather than the cheaper one. A success answers on the first attempt; an absence is only concluded once two independent sessions agree, across up to ten attempts. That verification is what stops a login wall being reported to you as a missing record. It is always 1 credit, even on the 2-credit /post/engagement endpoint.Accounts created from 27 August 2026 onwards are charged from their first request. Accounts that existed before then are not charged for 404s until 1 October 2026. Full breakdown at fetchin.io/pricing/credits.

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.
Solution: Upgrade your plan or wait for renewal. Do not retry blindly.

429 Too Many Requests

You exceeded your per-second request rate (code: "RATE_LIMITED"). A Retry-After header tells you how long to wait.
Solution: Back off and retry, honoring 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.
Solution: Retry with exponential backoff, honoring the Retry-After header. The same request will typically succeed shortly after.

500 Internal Server Error

An unexpected bug occurred in our API.
Solution: Retry with backoff. If it persists, contact support.

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

The error string is for humans and may change. The code is a stable contract — switch on it to decide how to react.
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.
429 and 503 responses include a Retry-After header (seconds). Wait at least that long before retrying.
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.
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

Failing requests do not consume credits, with one exception: a 404 costs 1 credit, because the lookup ran to completion before it could report the absence. Everything else is free, including 400, 401, 403, 429, 402 itself and every 5xx on our side. See Quotas and Rate Limits for details, or the full per-endpoint breakdown at fetchin.io/pricing/credits.