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.
{
  "error": "Service temporarily unable to serve this request. Please retry.",
  "code": "SERVICE_UNAVAILABLE"
}
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

HTTPcodeMeaningWhat to do
400MISSING_PARAMETERA required parameter is absentAdd the parameter and retry
400INVALID_PARAMETERA parameter value is invalidFix the value and retry
400INVALID_URNA LinkedIn URL/URN could not be parsedCheck the URL/URN format
401UNAUTHENTICATEDNo X-API-Key header was sentSend your API key
401INVALID_API_KEYThe API key is unknown or revokedCheck your key in the dashboard
403FORBIDDENAccess to this resource is not allowed
404PROFILE_NOT_FOUNDThe profile does not existDon’t retry; verify the input
404POST_NOT_FOUNDThe post does not existDon’t retry; verify the input
404COMPANY_NOT_FOUNDThe company does not existDon’t retry; verify the input
429RATE_LIMITEDPer-second request rate exceededBack off, honor Retry-After
429QUOTA_EXHAUSTEDMonthly credit quota exhaustedUpgrade or wait for renewal
500INTERNAL_ERRORAn unexpected bug on our sideRetry with backoff; contact support if it persists
502UPSTREAM_ERRORA genuine LinkedIn-side failureRetry with backoff
503SERVICE_UNAVAILABLEOur API is temporarily out of capacityRetry with backoff, honor Retry-After
504UPSTREAM_TIMEOUTAn upstream request timed outRetry with backoff

HTTP Status Codes

400 Bad Request

The request itself is malformed — a missing parameter (MISSING_PARAMETER), an invalid value (INVALID_PARAMETER), or an unparseable LinkedIn URL/URN (INVALID_URN).
{ "error": "Missing profileUrlOrUrn parameter", "code": "MISSING_PARAMETER" }
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).
{ "error": "Invalid API key", "code": "INVALID_API_KEY" }
Solution: Include a valid API key from your dashboard.

404 Not Found

We reached LinkedIn successfully, but the requested profile, post, or company genuinely does not exist.
{ "error": "LinkedIn profile not found", "code": "PROFILE_NOT_FOUND" }
Solution: Don’t retry — verify the URL/URN you sent.

429 Too Many Requests

Two distinct situations share this status. Branch on code:
  • RATE_LIMITED — you exceeded your per-second request rate. A Retry-After header tells you how long to wait.
  • QUOTA_EXHAUSTED — you ran out of monthly credits.
{ "error": "Rate limit exceeded. Try again later.", "code": "RATE_LIMITED" }
{ "error": "Quota exceeded. Upgrade your plan or wait for renewal.", "code": "QUOTA_EXHAUSTED" }
Solution: For RATE_LIMITED, back off and retry (honor Retry-After). For QUOTA_EXHAUSTED, upgrade your plan or wait for renewal.

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 a LinkedIn outage.
{ "error": "Service temporarily unable to serve this request. Please retry.", "code": "SERVICE_UNAVAILABLE" }
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.
{ "error": "Internal server error", "code": "INTERNAL_ERROR" }
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 LinkedIn’s side (as opposed to our capacity, which is 503). Retry with backoff.

Error Handling Examples

JavaScript/TypeScript

async function fetchProfile(profileUrl, apiKey) {
  const response = await fetch(
    `https://api.fetchin.io/api/v1/profile?profileUrlOrUrn=${encodeURIComponent(profileUrl)}`,
    { headers: { 'X-API-Key': apiKey } },
  );

  if (response.ok) return response.json();

  const { error, code } = await response.json();

  switch (code) {
    case 'MISSING_PARAMETER':
    case 'INVALID_PARAMETER':
    case 'INVALID_URN':
      throw new Error(`Bad request: ${error}`); // fix the request
    case 'INVALID_API_KEY':
    case 'UNAUTHENTICATED':
      throw new Error(`Auth: ${error}`);
    case 'QUOTA_EXHAUSTED':
      throw new Error('Out of credits — upgrade your plan.');
    case 'PROFILE_NOT_FOUND':
    case 'POST_NOT_FOUND':
    case 'COMPANY_NOT_FOUND':
      return null; // genuinely not found — don't retry
    default:
      throw new Error(`${code}: ${error}`);
  }
}

Python

import requests

def fetch_profile(profile_url, api_key):
    resp = requests.get(
        'https://api.fetchin.io/api/v1/profile',
        headers={'X-API-Key': api_key},
        params={'profileUrlOrUrn': profile_url},
    )
    if resp.ok:
        return resp.json()

    body = resp.json()
    code = body.get('code')

    if code in ('MISSING_PARAMETER', 'INVALID_PARAMETER', 'INVALID_URN'):
        raise ValueError(body['error'])          # fix the request
    if code == 'QUOTA_EXHAUSTED':
        raise RuntimeError('Out of credits — upgrade your plan.')
    if code in ('PROFILE_NOT_FOUND', 'POST_NOT_FOUND', 'COMPANY_NOT_FOUND'):
        return None                                # not found — don't retry
    raise RuntimeError(f"{code}: {body['error']}")

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.
Both are 429. RATE_LIMITED means slow down; QUOTA_EXHAUSTED means you need more credits. 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.