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.

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.

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

Failed requests (any 4xx/5xx) do not consume credits. See Quotas and Rate Limits for details.