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
413storage_quota_exceededMedia upload would exceed your plan’s storage limit
429rate_limit_exceededYour monthly post or interaction 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)

​
413 storage_quota_exceeded

Your media upload would push storage usage over the plan limit. Free plans are limited to 100 MB. Check your current usage with GET /v1/media/storage, delete unused media with DELETE /v1/media/:id, or upgrade your plan for unlimited storage. 
if error["code"] == "storage_quota_exceeded":
    # Check current usage
    usage = requests.get(f"{base_url}/v1/media/storage", headers=headers).json()
    print(f"Storage: {usage['used_bytes']} / {usage['limit_bytes']} bytes")
    # Consider deleting unused media or upgrading plan

​
429 rate_limit_exceeded

Your monthly post or interaction allowance is exhausted. Limits reset at the start of your next billing period, or upgrade your plan for unlimited capacity.

​
429 platform_rate_limit

The platform (not SocialAPI) is throttling. This does not consume your quota. 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 "storage_quota_exceeded":
      throw new Error("Storage full - delete unused media or upgrade plan");
    case "rate_limit_exceeded":
      throw new Error("Monthly limit hit - upgrade or wait for reset");
    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})`);
  }
}