Errors

Every error returns the same envelope: a stable error code and a human-readable message. Branch on error, never on message, which may be reworded.

{
  "error": "PROFILE_UNAVAILABLE",
  "message": "This profile does not exist or has been deactivated."
}

A request answered with an error is not billed.

Permanent errors

These fail the same way again. Do not retry the same request unchanged.

POST_* and PROFILE_* codes are permanent for that post or profile, not forever: a post made public again, or a profile reactivated, reads normally, though not always straight away.

Retryable errors

These are temporary. Retry the same request after the wait shown.

Whenever a response carries Retry-After, wait at least that many seconds, even on a code the table marks "Sometimes". Otherwise use exponential backoff with jitter: double the wait after each failure, add a random fraction of it, cap it at about five minutes, and give up after five or six attempts.

In a batch, each failed URL carries one of these codes in its result's error.code, an object rather than the plain error string of a single call. The batch itself still answers 200.

Routes that return these codes

• GET /v1/stats and POST /v1/stats/batch
• GET /v1/comments
• GET /v1/profile, the only route that returns the PROFILE_* codes

On the engagement verification routes:

• GET /admin/posts/thumbnail
• POST …/comments/refresh
• POST …/metrics/refresh
• POST /admin/creators/{userId}/refresh (for profiles, 404 means the profile no longer exists)

Liker fetching reports failures on the run's status and errorMessage instead; see Instagram likers.

Handling pattern

This function sorts a response into a result, a retry or a permanent failure. Not every error body is the API's JSON envelope: a 502 from a load balancer in between, for example, is not, so the status code decides when there is no error to read.

const RETRYABLE = new Set([
  "RATE_LIMITED",
  "SCRAPING_RATE_LIMITED",
  "INTERNAL_ERROR",
  "SCRAPING_ERROR",
  "SCRAPING_UNAVAILABLE",
  "UPSTREAM_TIMEOUT",
]);

type Outcome =
  | { kind: "ok"; body: unknown }
  | { kind: "retry"; retryAfterSeconds?: number }
  | { kind: "permanent"; error: string };

async function classify(res: Response): Promise<Outcome> {
  if (res.ok) return { kind: "ok", body: await res.json() };

  const retryAfter = Number(res.headers.get("Retry-After"));
  const { error } = await res.json().catch(() => ({ error: undefined }));
  const retryable = error ? RETRYABLE.has(error) : res.status === 429 || res.status >= 500;
  if (retryable) return { kind: "retry", retryAfterSeconds: retryAfter > 0 ? retryAfter : undefined };

  // POST_*, PROFILE_*, VALIDATION_ERROR and auth errors: permanent
  return { kind: "permanent", error: error ?? `HTTP ${res.status}` };
}

For the waiting and retrying around it, use the tested read() function in High-volume integration.

Get help with a request

Every response carries an X-Request-Id header. Log it next to the error, and quote it when you contact us about a request: it is how we find that request on our side. You can also send your own X-Request-Id, up to 128 letters, digits, _ or -, and the API uses it instead of generating one, so the id in your logs and ours is the same.