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:
| Message | Cause |
|---|---|
nothing to search: a name, a username or a phone is required | POST /create with fields but none of name, username, phone |
<code>:<field>, for example input_too_long:/fields/name | A search field broke an input rule. The value is never echoed back |
too_many_picks | More than 3 accounts of one network in a round's picked or in a confirm |
bad email | A 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 earlier | A classic POST /create/{reportId}/confirm listing accounts that differ from those added earlier for a network |
bcrypt: password length exceeds 72 bytes | A password longer than 72 bytes on sign-up or recovery |
stage quick needs a round_key | A first-look request without a round_key |
sources must be among the round's networks | A part names a network outside round_sources |
bad profile id | A malformed account id |
no source in search request | A 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
Authorizationheader on a call that needs an account (messageaccess denied: a guest session on a route that requires a signed-in account) - Expired or malformed JWT token: the
messageis the token validator's text POST /create/{reportId}/confirmorPOST /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:
| Message | Description |
|---|---|
to continue please upgrade your subscription | Signed-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 subscription | No 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:
| Message | Cause |
|---|---|
access denied | The report or resource belongs to another user, or a call is made without credentials where they are required |
report was already generated | The 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 available | People search is not enabled for this deployment |
classic search is not available | A 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 point | Phone search is turned off for this entry point |
not available for a phone lookup: its results are masked | A single-account call (matches, seed, account, linkedin, drop) on a phone lookup |
source cannot be searched | The 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:
404when the caller has no access to the report (or it was deleted)200{"generated": false}for a caller who does not own an unfinished report200{"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:
| Message | Cause |
|---|---|
report profiles were already confirmed | POST /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 search | A round with a different full phone number on a phone lookup |
report is not ready for chat: generation not completed | GET /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 report | The 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.
| Message | Cause |
|---|---|
nothing to search: a name, a username or a phone is required | A round with none of fields.name, fields.username, fields.phone; also a seed of a card that has no name to search by |
linkedin_only | A 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
| Message | Cause |
|---|---|
too many refinements for this report | The report's refinement-round cap is reached |
too many people search requests, slow down | Too many calls from this client |
Honour the Retry-After header.
500, 502 and 503: server side
| Status | Message | Meaning |
|---|---|---|
500 | internal error | A server failure; the cause is never in the body. Retry later; report it if it persists |
502 | the search service could not answer — please try again, with a short code in brackets | The search service answered with an error. Retry |
503 | the search service is busy — please try again in a moment | The search service is unavailable. Carries Retry-After. Retry |
503 | gateway_unavailable | A 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:
-
The confirm response —
loadshas an entry withstatus: "error"and the reason inerrorfor an account that cannot be in the report. -
SSE — subscribe to
GET /sse/{reportId}. You will receive afollowsevent withstatus: "error"and anerrorfield for the failed profile:{"type":"follows","status":"error","id":"123456789","source":"ig","error":"private"} -
Polling —
GET /check/{reportId}can includeloadErroranderrorSourcewhen 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 Code | Description | User Action |
|---|---|---|
private | Profile is private | Try a different profile |
notFound | Profile doesn't exist | Verify the username |
zeroFollows | No follows to analyze | Try a different profile |
followsPrivate | TikTok hid the following list (the account itself is not private) | Try a different profile |
optOut | User opted out | Cannot analyze |
unloaded | Temporary load failure (for example a timeout fetching follows) | Retry with a new report if needed |
unmapped | Cannot map profile | Contact support |
unexpected | Unexpected failure | Retry 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;
}