Skip to main content

Error Handling

This guide covers all error responses from the Socialprofiler API and how to handle them properly.

Error Response Format​

All errors follow a consistent format:

{
"code": 400,
"message": "Error description"
}

The body is {code, message} for every HTTP error status. It never contains a fieldError.

A few auth endpoints report a field-level failure differently: as HTTP 200 with a fieldError object in the body (no HTTP error status). This applies to POST /auth/signup, POST /auth/google and POST /auth/recovery/{hash}, and to a malformed email on sign-up and recovery. POST /auth/recovery never reports an unknown email: it answers {"status": "success"} whether or not an account exists, and its only account-independent refusal is the per-session "requests too often" error text. A wrong, used, expired or claimed hash on POST /auth/recovery/{hash} is a 404 {"code": 404, "message": "Wrong or expired link"}:

{
"status": "",
"fieldError": {
"field": "email",
"message": "user not found"
}
}

field is one of email, password or promocode. Check for fieldError, not for status: on sign-up, Google sign-in and POST /auth/recovery/{hash} the status is an empty string, and only POST /auth/recovery, GET /auth/recovery/{hash} and POST /auth/confirm/{hash} answer "status": "error". A 200 response is not automatically a success. Bad credentials on POST /auth/signin, a malformed email included, are never a soft error: they are always a 401 (see below).

HTTP Status Codes​

400 Bad Request​

Invalid request parameters or validation errors. The body is {"code": 400, "message": "..."}.

Common causes and messages:

MessageCause
nothing to search: a name, a username or a phone is requiredPOST /create with fields but none of name, username, phone
<code>:<field>, for example input_too_long:/fields/nameA search field broke an input rule. The value is never echoed back
too_many_picksMore than 3 accounts of one network in a round's picked or in a confirm
bad emailA malformed email on sign-up or recovery (this one is a field error, see above); sign-in answers 401
profiles do not match those added earlierA classic POST /create/{reportId}/confirm listing accounts that differ from those added earlier for a network
bcrypt: password length exceeds 72 bytesA password longer than 72 bytes on sign-up or recovery
stage quick needs a round_keyA first-look request without a round_key
sources must be among the round's networksA part names a network outside round_sources
bad profile idA malformed account id
no source in search requestA confirm that leaves the report no subject at all
{
"code": 400,
"message": "nothing to search: a name, a username or a phone is required"
}

How to handle:

if (response.status === 400) {
const error = await response.json();
showError(error.message);
}

401 Unauthorized​

Missing, invalid, or expired Bearer token / session on an endpoint that requires one.

Common causes:

  • Missing Authorization header on a call that needs an account (message access denied: a guest session on a route that requires a signed-in account)
  • Expired or malformed JWT token: the message is the token validator's text
  • POST /create/{reportId}/confirm or POST /people-search/drop/{reportId} called by a guest session (not signed in)
  • The account was deleted: account deleted
{
"code": 401,
"message": "access denied"
}

Wrong email or password on POST /auth/signin is also a 401, with the body {"code": 401, "message": "user not found"}. The body is the same for an unknown email, a wrong password and a deleted account, so it does not say which one it was. This 401 means bad credentials, not an expired token: do not call /auth/token/refresh for it, ask for the credentials again.

How to handle:

if (response.status === 401) {
// Token expired - refresh or re-authenticate
const newToken = await refreshToken();
// Retry original request with new token
return retryWithToken(originalRequest, newToken);
}

402 Payment Required​

Subscription or credits needed.

{
"code": 402,
"message": "to continue please upgrade your subscription"
}

Error variations:

MessageDescription
to continue please upgrade your subscriptionSigned-in user has no report credits. Returned by POST /create (report creation), not by confirm
You have reached search limit. Please Sign up to continue.A guest session used its free searches (also from POST /create)
guest_daily_limit: …A guest address used its free searches for the day. Carries Retry-After. Guests only
to continue with a book of insta add-on please upgrade your subscriptionNo Book of Insta credits

Note: confirming a report (POST /create/{reportId}/confirm) never returns 402. The credit check happens earlier, when the report is created. The credit itself is spent the first time the owner reads the finished report (GET /report/{reportId}); if you have none left at that point, the report is returned with blurred/placeholder data instead of an error.

A client that sends a Bearer token for a signed-in account does not meet guest_daily_limit.

How to handle:

if (response.status === 402) {
showUpgradePrompt();
// Redirect to subscription page
window.location.href = '/subscription';
}

403 Forbidden​

Access denied to the resource.

Common causes and messages:

MessageCause
access deniedThe report or resource belongs to another user, or a call is made without credentials where they are required
report was already generatedThe report has been built and can no longer be edited. Also on the classic add and search calls and on People search rounds
people search is not availablePeople search is not enabled for this deployment
classic search is not availableA classic call (GET /create/{reportId}, GET /create/{reportId}/{source}, POST /create/{reportId}/{source}/search, POST /create/{reportId}/{source}/add, or POST /create without fields) on a deployment where the classic flow is off. See Classic search
phone search is not available from this entry pointPhone search is turned off for this entry point
not available for a phone lookup: its results are maskedA single-account call (matches, seed, account, linkedin, drop) on a phone lookup
source cannot be searchedThe network (for example li) is turned off
{
"code": 403,
"message": "access denied"
}

How to handle:

if (response.status === 403) {
const error = await response.json();
if (error.message === 'report was already generated') {
// Report is locked, redirect to view
redirectToReport(reportId);
} else {
showAccessDeniedError();
}
}

404 Not Found​

Resource doesn't exist, or the caller may not see it.

Common causes:

  • Invalid or deleted report ID
  • A pick or confirm names an account that the report never showed (for a seed, also an account the search index does not hold: the account is not in the search index)
  • Interest not found
  • Friend not found
{
"code": 404,
"message": "report not found"
}

GET /check/{reportId} has its own rules, designed so a report ID is never confirmed to someone who may not see it:

  • 404 when the caller has no access to the report (or it was deleted)
  • 200 {"generated": false} for a caller who does not own an unfinished report
  • 200 {"generated": true} for a malformed or unknown report ID

The classic POST /create/{reportId}/{source}/add answers {"code": 404, "message": "profile not found"} when the profile id is not among the results.

How to handle:

if (response.status === 404) {
showNotFoundError();
// Redirect to dashboard
window.location.href = '/dashboard';
}

408 Request Timeout​

Search or operation timed out.

{
"code": 408,
"message": "request can not be completed. Please try again later"
}

How to handle:

if (response.status === 408) {
showRetryPrompt();
// Retry after delay
await sleep(2000);
return retryRequest(originalRequest);
}

409 Conflict​

The request conflicts with the state of the report.

Causes:

MessageCause
report profiles were already confirmedPOST /create/{reportId}/confirm called a second time. The earlier selection is untouched
this report is a phone lookup of another number: a new number is a new searchA round with a different full phone number on a phone lookup
report is not ready for chat: generation not completedGET /check/{reportId} with the header X-SP-Report-Check-Consumer: chat-agent on an unfinished report
book of insta add-on already ordered for this reportThe add-on was already ordered
{
"code": 409,
"message": "report profiles were already confirmed"
}

How to handle:

if (response.status === 409) {
// Already confirmed — treat as success and move on to waiting/fetching the report
proceedToWaitForReport(reportId);
}

422 Unprocessable Entity​

The request is well-formed, but the report's state refuses it. Nothing was changed or charged.

MessageCause
nothing to search: a name, a username or a phone is requiredA round with none of fields.name, fields.username, fields.phone; also a seed of a card that has no name to search by
linkedin_onlyA confirm whose accounts are all LinkedIn. A LinkedIn account is never a report subject: ask for an Instagram, Facebook, TikTok or X account
opted_out: …A pick, seed or confirm names an account whose owner opted out
confirm_limit: …A drop that would reopen a report already confirmed 5 times. Start a new search

428 Precondition Required​

captcha_required: …: a guest session starting a new search must pass a captcha. The body carries the keys needed to run it. A client that sends a Bearer token for a signed-in account does not meet it.

429 Too Many Requests​

MessageCause
too many refinements for this reportThe report's refinement-round cap is reached
too many people search requests, slow downToo many calls from this client

Honour the Retry-After header.

500, 502 and 503: server side​

StatusMessageMeaning
500internal errorA server failure; the cause is never in the body. Retry later; report it if it persists
502the search service could not answer — please try again, with a short code in bracketsThe search service answered with an error. Retry
503the search service is busy — please try again in a momentThe search service is unavailable. Carries Retry-After. Retry
503gateway_unavailableA confirm the search service could not answer whole. Nothing was confirmed or charged; carries Retry-After. Ask again
{
"code": 503,
"message": "gateway_unavailable"
}

How to handle:

if (response.status === 503 || response.status === 502) {
const wait = Number(response.headers.get('Retry-After') || 5);
await sleep(wait * 1000);
return retryRequest(originalRequest);
}

A single network of a People search round can also fail on its own: its panel then has ok: false and an error_code (for example gateway_unavailable) while the other panels are good. That is not an HTTP error.

Field-Specific Errors (Soft 200s)​

These are HTTP 200 responses with a fieldError on sign-up, recovery (a malformed email, or a rejected sign-in after the new password is set) and Google sign-in; see "Error Response Format" above. POST /auth/signin does not use them for bad credentials: they are a 401.

Email Field​

{
"status": "error",
"fieldError": {
"field": "email",
"message": "user not found"
}
}

("user not found" is never sent by POST /auth/recovery for an unknown email, which answers success. On POST /auth/recovery the status of the other refusals is "error"; elsewhere it is empty.) Also used for a malformed email address ("message": "bad email") and for signing up with an address that is already registered ("message": "user with this email was already registered").

Password Field​

{
"status": "",
"fieldError": {
"field": "password",
"message": "wrong password"
}
}

Promocode Field​

Every promocode failure (not found, expired, already used, or malformed) returns the same generic message — the specific reason is not exposed to the client, only the field name:

{
"status": "",
"fieldError": {
"field": "promocode",
"message": "Promo code is invalid, expired or was used up to the limit."
}
}

Profile Loading Errors (After Confirm)​

After you call POST /create/{reportId}/confirm, the API starts loading the selected account(s) and their subscriptions (follows). If loading fails for a profile (for example the account turned private, a service timeout, or follows could not be fetched), the API does not return an HTTP error for the whole report. Instead it marks that profile as failed and continues. You detect this through the confirm response, the stream or the status call.

When it happens: during the loading phase, right after confirm. One or more profiles may fail while others succeed (for example Instagram loads, Twitter fails).

Where you see it:

  1. The confirm response — loads has an entry with status: "error" and the reason in error for an account that cannot be in the report.

  2. SSE — subscribe to GET /sse/{reportId}. You will receive a follows event with status: "error" and an error field for the failed profile:

    {"type":"follows","status":"error","id":"123456789","source":"ig","error":"private"}
  3. Polling — GET /check/{reportId} can include loadError and errorSource when at least one profile failed to load. Use them to show which source failed and why.

Error codes (same as badReason and SSE error):

Error CodeDescriptionUser Action
privateProfile is privateTry a different profile
notFoundProfile doesn't existVerify the username
zeroFollowsNo follows to analyzeTry a different profile
followsPrivateTikTok hid the following list (the account itself is not private)Try a different profile
optOutUser opted outCannot analyze
unloadedTemporary load failure (for example a timeout fetching follows)Retry with a new report if needed
unmappedCannot map profileContact support
unexpectedUnexpected failureRetry with a new report if needed

Important: The report credit is spent when the owner first reads the finished report (GET /report/{reportId}), not on confirm. If loading fails for a profile, the report may still be available with data for other profiles; the failed one will not have follows/interests data. Handle status === "error" in SSE (or loadError from check) in your UI and inform the user that one account could not be loaded. To replace a failed account in a People search report, remove it with POST /people-search/drop/{reportId} and confirm again.

Error Handling Best Practices​

1. Implement Retry Logic​

async function fetchWithRetry(url, options, maxRetries = 3) {
let lastError;

for (let i = 0; i < maxRetries; i++) {
try {
const response = await fetch(url, options);

if (response.status === 503 || response.status === 502 || response.status === 408) {
// Retry on temporary errors
await sleep(Math.pow(2, i) * 1000);
continue;
}

return response;
} catch (error) {
lastError = error;
await sleep(Math.pow(2, i) * 1000);
}
}

throw lastError;
}

2. Token Refresh​

refreshToken() below should call POST /auth/token/refresh, which mints a new JWT from the session cookie set at sign-in (see Authentication for when the refresh is refused).

class ApiClient {
async request(url, options) {
let response = await fetch(url, {
...options,
headers: {
...options.headers,
'Authorization': `Bearer ${this.token}`
}
});

if (response.status === 401) {
// Try to refresh token
this.token = await this.refreshToken();

// Retry original request
response = await fetch(url, {
...options,
headers: {
...options.headers,
'Authorization': `Bearer ${this.token}`
}
});
}

return response;
}
}

3. User-Friendly Messages​

const ERROR_MESSAGES = {
'access denied': 'Please sign in to continue',
'to continue please upgrade your subscription': 'You\'ve used all your report credits. Upgrade your plan to continue.',
'report was already generated': 'This report is locked and can no longer be modified.',
'request can not be completed. Please try again later': 'The search is taking longer than expected. Please try again.',
'gateway_unavailable': 'The search is busy right now. Please try again in a moment.',
'linkedin_only': 'LinkedIn accounts cannot be the subject of a report. Choose an Instagram, Facebook, TikTok or X account.'
};

function getErrorMessage(apiError) {
return ERROR_MESSAGES[apiError.message] || apiError.message;
}

4. Logging for Debugging​

async function apiCall(url, options) {
const startTime = Date.now();

try {
const response = await fetch(url, options);
const duration = Date.now() - startTime;

if (!response.ok) {
const error = await response.json();
console.error('API Error', {
url,
status: response.status,
error,
duration
});
}

return response;
} catch (error) {
console.error('Network Error', {
url,
error: error.message,
duration: Date.now() - startTime
});
throw error;
}
}

Common Error Scenarios​

Scenario 1: Token Expired During Report Creation​

async function createReport(fields) {
try {
const response = await api.post('/create', { fields });
return response.data;
} catch (error) {
if (error.status === 401) {
// Re-authenticate and retry
await api.authenticate();
return createReport(fields);
}
throw error;
}
}

Scenario 2: An Account the Report Never Showed​

async function confirmAccounts(reportId, accounts) {
try {
await api.post(`/create/${reportId}/confirm`, accounts);
} catch (error) {
if (error.status === 404) {
// An account was not one of the report's cards: run a round again and let the user choose
const state = await api.get(`/people-search/state/${reportId}`);
showAccountSelector(state.data.panels);
return;
}
throw error;
}
}

Scenario 3: Handling Partial Failures​

async function confirmWithRecovery(reportId, accounts) {
const confirm = await api.post(`/create/${reportId}/confirm`, accounts);
const failed = (confirm.data.loads || []).filter(l => l.status === 'error');

for (const load of failed) {
// Take the failed account out; the search reopens
await api.post(`/people-search/drop/${reportId}`, { source: load.source, id: load.id });
}
if (failed.length > 0) {
console.warn(`${failed.length} accounts could not be loaded`);
showPartialLoadWarning(failed);
}
return failed.length < accounts.length;
}