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 ontitleordetail.- Retry
- Only when
retryableistrue, after theRetry-Afterseconds the response gives. - Request id
- Every response carries
X-Request-Id, and every problem repeats it asrequest_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
| Code | HTTP | Retryable | Action |
|---|---|---|---|
| missing_authorization | 401 | No | Send the API key as Authorization: Bearer <key>. |
| invalid_key | 401 | No | Check the whole key was copied, or create a new key in the console. |
| key_revoked | 401 | No | Create a new key in the console and use it instead. |
| key_expired | 401 | No | Create a new key in the console and use it instead. |
| invalid_token | 401 | No | Refresh the access token, then retry once with the new token. |
| organization_not_selected | 403 | No | Re-authorize the connection and choose an organization. |
| organization_access_revoked | 403 | No | Re-authorize against an organization the user still belongs to. |
| connection_revoked | 401 | No | Re-authorize the connection; the old token will not work again. |
| forbidden | 403 | No | Ask an organization owner or admin to do this, or to grant the role. |
| key_scope_insufficient | 403 | No | Use a full API key, or send estimate=true to quote it. |
The request itself
| Code | HTTP | Retryable | Action |
|---|---|---|---|
| invalid_request | 400 | No | Fix the field named in detail, then send the corrected request. |
| unsupported_platform | 400 | No | Use a platform this operation lists as supported. |
| unsupported_kind | 422 | No | Do not repeat this request; nothing was charged. Use an operation that serves this kind. |
| kind_deprecated | 400 | No | Track the Creator, a Hashtag or a Sound instead of a Video. |
| focus_unsupported_kind | 422 | No | Send the Tracker without focus, or pick a kind in supported_kinds. |
| video_too_long | 422 | No | Pick a video under max_duration_seconds; this one will never qualify. |
| not_found | 404 | No | Check the id or handle; list your resources to find the right one. |
| comment_not_found | 404 | No | Read the video's comments page first and pass one of its item ids as comment_id. |
| idempotency_conflict | 409 | No | Resend the original payload with this key, or use a new key for the new payload. |
| run_not_ready | 409 | Yes | Poll the Run until it settles, then read again. If it failed, start a new Run. |
| advertiser_ambiguous | 409 | No | Ask again with one of candidates' page_id or url. |
| collection_kind_mismatch | 409 | No | Add this target to a Collection of its own kind. |
| collection_name_taken | 409 | No | Use the Collection in collection_id, or pick another name. |
Money
| Code | HTTP | Retryable | Action |
|---|---|---|---|
| insufficient_balance | 402 | No | Tell the Customer to top up the Balance, then repeat the same request. |
| max_credits_exceeded | 402 | No | Narrow the call until estimate_credits fits, or raise max_credits if the Customer allows. |
| key_spend_cap_exceeded | 402 | No | Wait until resets_at, or ask the Customer to raise the cap. |
Limits
| Code | HTTP | Retryable | Action |
|---|---|---|---|
| rate_limit_exceeded | 429 | Yes | Wait retry_after_seconds, then retry the same request. |
| concurrency_limit_exceeded | 429 | Yes | Wait retry_after_seconds for a running Run to finish, then retry. |
| tracker_limit_exceeded | 409 | No | Pause or delete a Tracker, then retry. |
| collection_limit_exceeded | 409 | No | Delete a Collection you no longer use, then retry. |
| webhook_limit_exceeded | 409 | No | Delete an endpoint you no longer deliver to, then retry. |
| webhook_rotation_in_progress | 409 | Yes | Wait until overlap_expires_at, then rotate again. |
Upstream and ours
| Code | HTTP | Retryable | Action |
|---|---|---|---|
| media_unavailable | 502 | No | Tell the Customer the video is deleted, private or blocked; pick another. |
| vendor_error | 502 | Yes | Retry with a backoff; nothing was charged. |
| source_unavailable | 503 | Yes | Wait retry_after_seconds, then retry; do not treat this as an empty result. |
| service_unavailable | 503 | Yes | Wait retry_after_seconds, then retry; nothing was charged. |
| internal_error | 500 | Yes | Retry 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.