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 | code | Meaning | What to do |
|---|---|---|---|
| 400 | MISSING_PARAMETER | A required parameter is absent | Add the parameter and retry |
| 400 | INVALID_PARAMETER | A parameter value is invalid | Fix the value and retry |
| 400 | INVALID_URN | A LinkedIn URL/URN could not be parsed | Check the URL/URN format |
| 401 | UNAUTHENTICATED | No X-API-Key header was sent | Send your API key |
| 401 | INVALID_API_KEY | The API key is unknown or revoked | Check your key in the dashboard |
| 403 | FORBIDDEN | Access to this resource is not allowed | — |
| 404 | PROFILE_NOT_FOUND | The profile does not exist | Don’t retry; verify the input |
| 404 | POST_NOT_FOUND | The post does not exist | Don’t retry; verify the input |
| 404 | COMPANY_NOT_FOUND | The company does not exist | Don’t retry; verify the input |
| 429 | RATE_LIMITED | Per-second request rate exceeded | Back off, honor Retry-After |
| 429 | QUOTA_EXHAUSTED | Monthly credit quota exhausted | Upgrade or wait for renewal |
| 500 | INTERNAL_ERROR | An unexpected bug on our side | Retry with backoff; contact support if it persists |
| 502 | UPSTREAM_ERROR | A genuine LinkedIn-side failure | Retry with backoff |
| 503 | SERVICE_UNAVAILABLE | Our API is temporarily out of capacity | Retry with backoff, honor Retry-After |
| 504 | UPSTREAM_TIMEOUT | An upstream request timed out | Retry 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).
401 Unauthorized
TheX-API-Key header is missing (UNAUTHENTICATED) or invalid
(INVALID_API_KEY).
404 Not Found
We reached LinkedIn successfully, but the requested profile, post, or company genuinely does not exist.429 Too Many Requests
Two distinct situations share this status. Branch oncode:
RATE_LIMITED— you exceeded your per-second request rate. ARetry-Afterheader tells you how long to wait.QUOTA_EXHAUSTED— you ran out of monthly credits.
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.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 LinkedIn’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
Both are
429. RATE_LIMITED means slow down; QUOTA_EXHAUSTED means you
need more credits. 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.