Private and deleted accounts

When a profile is private or gone, the API tells you exactly that, with a distinct error code you can branch on. These are definitive answers, not failures: your pipeline should store them, not retry them.

The three answers

{
  "error": {
    "code": "PROFILE_PRIVATE",
    "message": "This profile is private.",
    "requestId": "req_01j8…",
    "retryable": false
  }
}

Why these answers are billable

"This account is private" and "this account no longer exists" are useful results: the API did the work to determine them. They bill like any answered request. Genuine failures (provider errors, internal errors) are never charged. The retryable flag separates the two: definitive answers are retryable: false.

Handling them in a pipeline

• Store the answer with a timestamp. An account private today may be public next month. Re-check on your own schedule instead of hammering.
• Do not treat 404 as "try again". PROFILE_NOT_FOUND with a valid identifier means the account is gone from public view: deleted, banned, or deactivated. The platforms do not say which, so neither do we.
• Distinguish rename from deletion. Handles are mutable. If you stored the platform id from an earlier response, look up by ID: a renamed account still resolves, a deleted one returns PROFILE_NOT_FOUND. This is the main reason to store IDs, not handles.
• Expect transitions mid-pagination. An account can flip private while you page through its posts. Handle PROFILE_PRIVATE on any page, not just the first.

Posts and comments follow the same pattern

POST_NOT_FOUND and COMMENT_NOT_FOUND behave identically: definitive, billable, retryable: false. A deleted post inside an existing profile is an answer about that post, not an error in your request.

The code names the resource the endpoint reads. The comments or likers of a missing post return POST_NOT_FOUND. The replies to a missing comment return COMMENT_NOT_FOUND. A missing hashtag, location, music track, playlist, or subreddit returns RESOURCE_NOT_FOUND, which behaves the same way.

The full error catalog is in envelope and errors.