Errors

Errors return a short Socify message only : never raw upstream details. Check ok === false (when present) and the HTTP status before reading data.

Status codes

Code	Status	Description
400	Bad Request	Missing or invalid parameters.
401	Unauthorized	Missing or invalid API key.
402	Payment Required	Insufficient credits.
404	Not Found	Unknown platform or resource.
502	Bad Gateway	Lookup failed.
503	Unavailable	Service temporarily unavailable.

Error shape

Typical error body. Some codes omit ok / params and only return error.

{
  "ok": false,
  "error": "insufficient credits",
  "params": { "username": "natgeo" },
  "latency": 12
}

Handling errors

Map each status to a concrete client action:

400 : Bad Request

Missing or invalid query params (e.g. missing required parameter: username). Fix the request; do not retry unchanged.

401 : Unauthorized

Missing, malformed, revoked, or unknown API key ({ "error": "unauthorized" }). Rotate/fix the key. See Authentication. Do not retry with the same secret.

402 : Payment Required

Balance too low. Body may include credits_required and credits_balance. Pause lookups, upgrade or wait for the monthly reset. See Credits.

{
  "error": "insufficient credits",
  "credits_required": 1,
  "credits_balance": 0
}

404 : Not Found

Unknown platform / resource, or the social entity itself was not found upstream (resource not found /unknown platform or resource). Verify the path and handle id; do not retry blindly.

502 : Bad Gateway

Lookup failed after auth and credit check. Common messages: lookup failed, rate limited : try again shortly (upstream platform throttle: Socify does not enforce account req/min caps), upstream timeout : try again, invalid request parameters. Retry only when the message implies a transient failure (see below). Credits may already have been reserved for the attempt : check your usage in the dashboard.

503 : Unavailable

Service temporarily unavailable (capacity / provider keys). Back off and retry with the strategy below. Prefer exponential backoff with jitter; alert if it persists beyond a few minutes.

Retry strategy

Status	Retry?	Guidance
400	No	Fix params; retrying wastes credits.
401	No	Replace the API key first.
402	No	Wait for credit reset or upgrade the plan.
404	No	Correct platform/resource/id; entity may not exist.
502	Sometimes	Retry on timeout / rate-limit messages only. Cap at 3 attempts with exponential backoff (e.g. 1s → 2s → 4s) + jitter. Do not retry `invalid request parameters`.
503	Yes	Exponential backoff with jitter. Max 3–5 attempts, then fail the job and alert.

Pseudocode for safe retries:

async function lookupWithRetry(url, headers, { maxAttempts = 3 } = {}) {
  let delayMs = 1000;
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const res = await fetch(url, { headers });
    const body = await res.json().catch(() => ({}));
    if (res.ok) return body;

    const retryable =
      res.status === 503 ||
      (res.status === 502 &&
        /timeout|rate limited/i.test(String(body.error || '')));

    if (!retryable || attempt === maxAttempts) {
      throw Object.assign(new Error(body.error || res.statusText), {
        status: res.status,
        body,
      });
    }

    const jitter = Math.floor(Math.random() * 250);
    await new Promise((r) => setTimeout(r, delayMs + jitter));
    delayMs *= 2;
  }
}

Errors

Errors return a short Socify message only : never raw upstream details. Check ok === false (when present) and the HTTP status before reading data.

Status codes

Code	Status	Description
400	Bad Request	Missing or invalid parameters.
401	Unauthorized	Missing or invalid API key.
402	Payment Required	Insufficient credits.
404	Not Found	Unknown platform or resource.
502	Bad Gateway	Lookup failed.
503	Unavailable	Service temporarily unavailable.

Error shape

Typical error body. Some codes omit ok / params and only return error.

{
  "ok": false,
  "error": "insufficient credits",
  "params": { "username": "natgeo" },
  "latency": 12
}

Handling errors

Map each status to a concrete client action:

400 : Bad Request

Missing or invalid query params (e.g. missing required parameter: username). Fix the request; do not retry unchanged.

401 : Unauthorized

Missing, malformed, revoked, or unknown API key ({ "error": "unauthorized" }). Rotate/fix the key. See Authentication. Do not retry with the same secret.

402 : Payment Required

Balance too low. Body may include credits_required and credits_balance. Pause lookups, upgrade or wait for the monthly reset. See Credits.

{
  "error": "insufficient credits",
  "credits_required": 1,
  "credits_balance": 0
}

404 : Not Found

Unknown platform / resource, or the social entity itself was not found upstream (resource not found /unknown platform or resource). Verify the path and handle id; do not retry blindly.

502 : Bad Gateway

503 : Unavailable

Service temporarily unavailable (capacity / provider keys). Back off and retry with the strategy below. Prefer exponential backoff with jitter; alert if it persists beyond a few minutes.

Retry strategy

Status	Retry?	Guidance
400	No	Fix params; retrying wastes credits.
401	No	Replace the API key first.
402	No	Wait for credit reset or upgrade the plan.
404	No	Correct platform/resource/id; entity may not exist.
502	Sometimes	Retry on timeout / rate-limit messages only. Cap at 3 attempts with exponential backoff (e.g. 1s → 2s → 4s) + jitter. Do not retry `invalid request parameters`.
503	Yes	Exponential backoff with jitter. Max 3–5 attempts, then fail the job and alert.

Pseudocode for safe retries:

async function lookupWithRetry(url, headers, { maxAttempts = 3 } = {}) {
  let delayMs = 1000;
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const res = await fetch(url, { headers });
    const body = await res.json().catch(() => ({}));
    if (res.ok) return body;

    const retryable =
      res.status === 503 ||
      (res.status === 502 &&
        /timeout|rate limited/i.test(String(body.error || '')));

    if (!retryable || attempt === maxAttempts) {
      throw Object.assign(new Error(body.error || res.statusText), {
        status: res.status,
        body,
      });
    }

    const jitter = Math.floor(Math.random() * 250);
    await new Promise((r) => setTimeout(r, delayMs + jitter));
    delayMs *= 2;
  }
}

Errors

Errors return a short Socify message only : never raw upstream details. Check ok === false (when present) and the HTTP status before reading data.

Status codes

Code	Status	Description
400	Bad Request	Missing or invalid parameters.
401	Unauthorized	Missing or invalid API key.
402	Payment Required	Insufficient credits.
404	Not Found	Unknown platform or resource.
502	Bad Gateway	Lookup failed.
503	Unavailable	Service temporarily unavailable.

Error shape

Typical error body. Some codes omit ok / params and only return error.

{
  "ok": false,
  "error": "insufficient credits",
  "params": { "username": "natgeo" },
  "latency": 12
}

Handling errors

Map each status to a concrete client action:

400 : Bad Request

Missing or invalid query params (e.g. missing required parameter: username). Fix the request; do not retry unchanged.

401 : Unauthorized

Missing, malformed, revoked, or unknown API key ({ "error": "unauthorized" }). Rotate/fix the key. See Authentication. Do not retry with the same secret.

402 : Payment Required

Balance too low. Body may include credits_required and credits_balance. Pause lookups, upgrade or wait for the monthly reset. See Credits.

{
  "error": "insufficient credits",
  "credits_required": 1,
  "credits_balance": 0
}

404 : Not Found

Unknown platform / resource, or the social entity itself was not found upstream (resource not found /unknown platform or resource). Verify the path and handle id; do not retry blindly.

502 : Bad Gateway

503 : Unavailable

Service temporarily unavailable (capacity / provider keys). Back off and retry with the strategy below. Prefer exponential backoff with jitter; alert if it persists beyond a few minutes.

Retry strategy

Status	Retry?	Guidance
400	No	Fix params; retrying wastes credits.
401	No	Replace the API key first.
402	No	Wait for credit reset or upgrade the plan.
404	No	Correct platform/resource/id; entity may not exist.
502	Sometimes	Retry on timeout / rate-limit messages only. Cap at 3 attempts with exponential backoff (e.g. 1s → 2s → 4s) + jitter. Do not retry `invalid request parameters`.
503	Yes	Exponential backoff with jitter. Max 3–5 attempts, then fail the job and alert.

Pseudocode for safe retries:

async function lookupWithRetry(url, headers, { maxAttempts = 3 } = {}) {
  let delayMs = 1000;
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const res = await fetch(url, { headers });
    const body = await res.json().catch(() => ({}));
    if (res.ok) return body;

    const retryable =
      res.status === 503 ||
      (res.status === 502 &&
        /timeout|rate limited/i.test(String(body.error || '')));

    if (!retryable || attempt === maxAttempts) {
      throw Object.assign(new Error(body.error || res.statusText), {
        status: res.status,
        body,
      });
    }

    const jitter = Math.floor(Math.random() * 250);
    await new Promise((r) => setTimeout(r, delayMs + jitter));
    delayMs *= 2;
  }
}