Skip to main content
All errors return JSON with a consistent shape: 
{
  "error": "human-readable message",
  "code": "machine_readable_code"
}
Use code for programmatic error handling; use error for logging and display.

​
Error codes

HTTPCodeWhen it occurs
400missing_metadataA required field is missing in the request body or query
400unsupported_platformThe platform value is not recognized
401unauthorizedAPI key is missing, invalid, or revoked
401invalid_tokenThe connected account’s OAuth token is expired or revoked
401invalid_credentialsThe platform rejected the stored credentials
403unauthorizedThe OAuth state token belongs to a different API key
404account_not_foundThe account ID does not belong to your workspace
404not_foundThe requested resource does not exist
409account_already_linkedThis social account is already connected
429rate_limit_exceededYour daily API call limit is exceeded
429platform_rate_limitThe upstream platform’s own rate limit was hit
500—Internal server error (contact support)
501not_supportedThis operation is not supported on this platform

​
Handling specific cases

​
401 invalid_token

The user’s OAuth token expired. Your app should reconnect the account by re-running the OAuth flow. 
if error["code"] == "invalid_token":
    # Trigger reconnect flow for this account_id
    redirect_to_reconnect(account_id)

​
429 rate_limit_exceeded

Back off and retry tomorrow, or upgrade your plan.

​
429 platform_rate_limit

The platform (not SocialAPI) is throttling. This does not count against your daily limit. Wait a few minutes and retry.

​
501 not_supported

The operation is not available on this platform. For example, Instagram does not have reviews — calling GET /accounts/{id}/reviews on an Instagram account returns 501. Check the Connectors section for each platform’s supported operations.

​
Example error handling

const resp = await fetch(`https://api.social-api.ai/v1/accounts/${accountId}/comments`, {
  headers: { Authorization: `Bearer ${apiKey}` }
});

if (!resp.ok) {
  const err = await resp.json();
  switch (err.code) {
    case "invalid_token":
      await reconnectAccount(accountId);
      break;
    case "rate_limit_exceeded":
      throw new Error("Daily limit hit — retry tomorrow");
    case "platform_rate_limit":
      await sleep(60_000);
      return retry();
    case "not_supported":
      console.warn(`Platform does not support this operation: ${err.error}`);
      return null;
    default:
      throw new Error(`API error: ${err.error} (${err.code})`);
  }
}