Skip to content
For AI agents: a documentation index is available at /llms.txt. Every docs page is also available as markdown: add .md to its URL. To connect, read /agents.md.

Concepts

Errors

The problem document every failure returns, the stable codes to branch on, and what to do about each one.

Body
Every failure returns application/problem+json, in one shape.
Branch on
code, one of 37 stable codes. Never match on title or detail.
Retry
Only when retryable is true, after the Retry-After seconds the response gives.
Request id
Every response carries X-Request-Id, and every problem repeats it as request_id.

Every failure returns an HTTP status and a body of type application/problem+json. Inside the body is a stable code, the one part of an error to write code against. The body also says whether a retry can work and what to do next.

Every failure returns one problem document

Four fields identify the problem, two more help you recover, and every problem carries a request id. Most problems add detail, a sentence about this occurrence. Some add fields of their own, such as a balance, a limit, the id of a conflicting Run, or retry_after_seconds with the same wait as the Retry-After header.

type
A URL identifying the kind of problem.
title
A short summary for a person.
status
The HTTP status, repeated in the body.
code
The machine-readable name to branch on.
retryable
Whether the same request, sent again after any wait the body names, can succeed.
action
The next step, in one sentence.
remedy
The fuller remedy from the code's reference page, so you can act on the body alone.
request_id
The id of this request, for support.

retryable is true when the same request can succeed later unchanged: a rate or concurrency limit, an upstream outage, an error on our side, or a Run not yet settled. It is false when the request has to change or a person has to act.

When to read the code, the status or the prose

Branch on code. Codes are added deliberately, are never renamed, and mean the same thing on every endpoint that returns them. title and detail are written for a person reading a log. Their wording changes whenever a clearer one turns up, so matching on them breaks without warning.

A status on its own is too coarse. 2 codes share 429 and need different handling, and 403 covers 4 distinct authorization failures. Use the status only to decide whether a retry is plausible at all, and retryable to decide it for certain.

Request ids

Every response carries an X-Request-Id header, and every problem repeats it as request_id. Quote it to support and we can find the request. Send your own X-Request-Id (1-128 of A-Z a-z 0-9 . _ : -) and it is echoed back. Otherwise one is generated.

A failed Run, read again, carries the id of that read. One MCP tool call is one request with one id.

Which field to fix

An invalid_request about a field lists each bad one in errors, as { path, message }. path is the dotted field path, such as collection_ids.1, or the parameter or header, such as wait. It is empty when the input as a whole is wrong.

detail keeps the joined sentence. A body that is not JSON has no errors.

Every code

Retryable and Action are the retryable and action every body of that code carries. Each code links to its own page, which explains the causes and the remedy in full.

Credentials

CodeHTTPRetryableAction
missing_authorization401NoSend the API key as Authorization: Bearer <key>.
invalid_key401NoCheck the whole key was copied, or create a new key in the console.
key_revoked401NoCreate a new key in the console and use it instead.
key_expired401NoCreate a new key in the console and use it instead.
invalid_token401NoRefresh the access token, then retry once with the new token.
organization_not_selected403NoRe-authorize the connection and choose an organization.
organization_access_revoked403NoRe-authorize against an organization the user still belongs to.
connection_revoked401NoRe-authorize the connection; the old token will not work again.
forbidden403NoAsk an organization owner or admin to do this, or to grant the role.
key_scope_insufficient403NoUse a full API key, or send estimate=true to quote it.

The request itself

CodeHTTPRetryableAction
invalid_request400NoFix the field named in detail, then send the corrected request.
unsupported_platform400NoUse a platform this operation lists as supported.
unsupported_kind422NoDo not repeat this request; nothing was charged. Use an operation that serves this kind.
kind_deprecated400NoTrack the Creator, a Hashtag or a Sound instead of a Video.
focus_unsupported_kind422NoSend the Tracker without focus, or pick a kind in supported_kinds.
video_too_long422NoPick a video under max_duration_seconds; this one will never qualify.
not_found404NoCheck the id or handle; list your resources to find the right one.
comment_not_found404NoRead the video's comments page first and pass one of its item ids as comment_id.
idempotency_conflict409NoResend the original payload with this key, or use a new key for the new payload.
run_not_ready409YesPoll the Run until it settles, then read again. If it failed, start a new Run.
advertiser_ambiguous409NoAsk again with one of candidates' page_id or url.
collection_kind_mismatch409NoAdd this target to a Collection of its own kind.
collection_name_taken409NoUse the Collection in collection_id, or pick another name.

Money

CodeHTTPRetryableAction
insufficient_balance402NoTell the Customer to top up the Balance, then repeat the same request.
max_credits_exceeded402NoNarrow the call until estimate_credits fits, or raise max_credits if the Customer allows.
key_spend_cap_exceeded402NoWait until resets_at, or ask the Customer to raise the cap.

Limits

CodeHTTPRetryableAction
rate_limit_exceeded429YesWait retry_after_seconds, then retry the same request.
concurrency_limit_exceeded429YesWait retry_after_seconds for a running Run to finish, then retry.
tracker_limit_exceeded409NoPause or delete a Tracker, then retry.
collection_limit_exceeded409NoDelete a Collection you no longer use, then retry.
webhook_limit_exceeded409NoDelete an endpoint you no longer deliver to, then retry.
webhook_rotation_in_progress409YesWait until overlap_expires_at, then rotate again.

Upstream and ours

CodeHTTPRetryableAction
media_unavailable502NoTell the Customer the video is deleted, private or blocked; pick another.
vendor_error502YesRetry with a backoff; nothing was charged.
source_unavailable503YesWait retry_after_seconds, then retry; do not treat this as an empty result.
service_unavailable503YesWait retry_after_seconds, then retry; nothing was charged.
internal_error500YesRetry with a backoff, reusing any Idempotency-Key; report reference_id if it persists.

Three codes to handle first

402: insufficient balance

The balance is checked before any work starts, so a 402 means nothing happened: no Run, no charge, no partial state to reconcile. The body carries what you have and what the call needed. Top up and repeat the identical request. For Research and enriched searches the check is against the worst-case quote.

The same code can appear on one item of a partial Run. The balance ran short while the Run was working, so the completed items were charged in order up to the balance and the rest were not. See pricing and estimates for how to avoid it.

409: idempotency conflict

Replaying an Idempotency-Key with the same payload returns the original Run, which makes a retry safe. Replaying it with a different payload is a conflict. We will not do new work under an old key, or return the old answer for a new question. The body names the Run the key already belongs to.

409 · idempotency_conflict

{
  "type": "https://www.shortsintel.com/docs/reference/errors/idempotency_conflict",
  "title": "Idempotency conflict",
  "status": 409,
  "code": "idempotency_conflict",
  "detail": "This Idempotency-Key was used with a different payload.",
  "retryable": false,
  "action": "Resend the original payload with this key, or use a new key for the new payload.",
  "run_id": "run_8f2c1ad04b"
}

Generate one key per logical request and reuse it only for retries of that exact request.

429: too fast, or too much at once

2 codes answer 429. rate_limit_exceeded means requests are arriving too quickly on this credential. concurrency_limit_exceeded means too much paid work is already in flight, and a slot frees when one of your Runs finishes.

429 · `rate_limit_exceeded` or `concurrency_limit_exceeded`, with `Retry-After`.

{
  "type": "https://www.shortsintel.com/docs/reference/errors/rate_limit_exceeded",
  "title": "Rate limit exceeded",
  "status": 429,
  "code": "rate_limit_exceeded",
  "detail": "60 requests per minute per key. Retry after the number of seconds in `Retry-After`.",
  "retryable": true,
  "action": "Wait `retry_after_seconds`, then retry the same request.",
  "limit": 60,
  "retry_after_seconds": 12,
  "resets_at": "2026-09-08T09:15:00.000Z"
}

Both carry Retry-After in the response headers and the same number as retry_after_seconds in the body, which is what an MCP caller sees. Sleep for that many seconds. Do not retry immediately or invent your own backoff. The limits are described in authentication and limits.

A 503 source_unavailable carries both too. Wait, then retry, and do not read it as an empty result.

Errors that live on a Run

A call that starts work and then cannot finish it answers 200 or 202, and the failure lands on the Run instead. A failed Run carries a problem document in this same shape, and a partial Run carries one per item that did not arrive. The fields, the codes and the rule about branching are the same.

Limits that return an error

Requests
60 a minute per key, or per user over OAuth, free reads included. Over it: rate_limit_exceeded.
Runs in flight
10 at once per organization. Over it: concurrency_limit_exceeded.
Your request id
1 to 128 letters, digits, dots, underscores, colons or hyphens. Any other value is replaced with a generated id.

Example: a 402 problem document

A video lookup with too little balance returns this body. Branch on code, show action to the person who can top up, and keep request_id for support.

402 · insufficient_balance

{
  "type": "https://www.shortsintel.com/docs/reference/errors/insufficient_balance",
  "title": "Insufficient balance",
  "status": 402,
  "code": "insufficient_balance",
  "detail": "Your balance is 0 Credits and this operation needs 3 Credits. Nothing was charged.",
  "retryable": false,
  "action": "Tell the Customer to top up the Balance, then repeat the same request.",
  "balance_credits": 0,
  "required_credits": 3
}

Questions about errors

Which field should my code branch on?

code. It is never renamed. title and detail can change wording at any time.

Can I retry a request that failed?

When retryable is true, yes, after the Retry-After seconds. If no Run came back, as on a timeout or a 429, resend the same Idempotency-Key. If a Run came back failed, use a new key: the old key returns that failed Run and does no new work.

Was I charged for a request that returned an error?

No for a 402 or 429: no Run was created. A partial Run charges only for the items that arrived.

What should I send to support?

The request_id from the body, or the X-Request-Id header.