Errors

Success envelope

Successful JSON responses are wrapped in a { data, meta } envelope.

• data: endpoint-specific payload
• meta: response metadata (including a support-friendly request ID)

Example (200 success):

{
  "data": {
    "lookupStatus": "found",
    "profile": {
      "platform": "tiktok",
      "handle": "charlidamelio",
      "displayName": "charli",
      "bio": "hey",
      "avatarUrl": "https://example.com/avatar-large.jpg",
      "verified": true,
      "profileUrl": "https://www.tiktok.com/@charlidamelio",
      "privateAccount": false
    },
    "metrics": {
      "followers": 150000000,
      "following": 123,
      "likes": 12345678901,
      "posts": 456
    }
  },
  "meta": {
    "requestId": "req_01example",
    "creditsCharged": 1,
    "version": "v1"
  }
}

The exact data shape varies by endpoint — check the operation’s 200 schema in the API reference.

Outcome semantics

Some endpoints return “domain outcomes” in a 200 response instead of returning a 4xx. For example, a profile lookup can return lookupStatus: "not_found" with HTTP 200:

{
  "data": {
    "lookupStatus": "not_found",
    "profile": null,
    "metrics": null
  },
  "meta": {
    "requestId": "req_01example",
    "creditsCharged": 1,
    "version": "v1"
  }
}

Rule of thumb:

• If HTTP is 200: parse the success envelope and check the endpoint’s domain status fields (like data.lookupStatus).
• If HTTP is not 200: parse the standard error envelope below.

Common business-level outcomes

Depending on the endpoint, a successful response may still represent different lookup outcomes:

• found: the requested entity was resolved and the expected data is present
• not_found: the requested target does not exist or could not be resolved as an existing entity
• private: the entity exists but the relevant data is not publicly available

Always confirm the exact response schema on the endpoint page in the API reference.

Empty result vs not found

Do not assume an empty collection always means “not found.”

• a profile can exist while a media list is currently empty
• a target can be valid but private
• a target can truly be missing

Preserve that distinction in your client instead of collapsing all misses into the same case.

Disambiguating list routes

Some list routes can return HTTP 200 with an empty data.* collection for more than one reason, and may not expose data.lookupStatus.

If that distinction matters:

1. Call the platform profile route for the same handle (GET /v1/{platform}/profiles/{handle}).
2. Interpret data.lookupStatus (found, private, not_found) from the profile response.
3. Only then call the list route if you still need feed items.

If you only need “posts or nothing,” you can skip the profile preflight and accept the ambiguity.

Client logic

1. check HTTP status
2. if status is 200, inspect the endpoint-specific outcome fields
3. only enter your HTTP error handling path for non-200 responses

With the TypeScript SDK, map the same steps to result.ok and result.value.data.

Credits and outcomes

Some metered endpoints may still charge credits when the lookup attempt completed successfully, even if the business-level result is not_found or private.

See Credits for the billing side of that behavior.

Error body

Error responses return JSON with a shared { error } envelope:

{
  "error": {
    "code": "unauthorized",
    "message": "Missing API key.",
    "requestId": "req_01example"
  }
}

error.code

error.code is machine-readable and comes from a stable set of values:

• bad_request
• unauthorized
• insufficient_credits
• lookup_failed
• transcript_target_not_video
• video_too_long_for_transcription
• temporarily_unavailable
• internal_error

Refer to the API reference for the exact codes used by each HTTP status on a given route (for example 400, 401, 402, 502, 503).

Request ID

You’ll see a request ID in both success and error responses:

• Success: meta.requestId
• Error: error.requestId

Include it when contacting support, and consider logging it in your client on failures.

Common cases

• 400 — invalid request (see error.code: "bad_request") or a known limitation such as transcript_target_not_video or video_too_long_for_transcription.
• 401 — missing or invalid API key (see error.code: "unauthorized").
• 402 — insufficient credits (see error.code: "insufficient_credits").
• 500 — unexpected error (see error.code: "internal_error").
• 502 — lookup could not be completed from the response (see error.code: "lookup_failed").
• 503 — service temporarily unavailable; safe to retry with backoff (see error.code: "temporarily_unavailable").