# Errors

> For the complete documentation index, see [llms.txt](https://www.shortsintel.com/llms.txt). Every docs page is also available as markdown: add .md to its URL. To connect, read [agents.md](https://www.shortsintel.com/agents.md).

> 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 39 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

| Code | HTTP | Retryable | Action |
| --- | --- | --- | --- |
| [missing_authorization](https://www.shortsintel.com/docs/reference/errors/missing_authorization) | 401 | No | Send the API key as `Authorization: Bearer <key>`. |
| [invalid_key](https://www.shortsintel.com/docs/reference/errors/invalid_key) | 401 | No | Check the whole key was copied, or create a new key in the console. |
| [key_revoked](https://www.shortsintel.com/docs/reference/errors/key_revoked) | 401 | No | Create a new key in the console and use it instead. |
| [key_expired](https://www.shortsintel.com/docs/reference/errors/key_expired) | 401 | No | Create a new key in the console and use it instead. |
| [invalid_token](https://www.shortsintel.com/docs/reference/errors/invalid_token) | 401 | No | Refresh the access token, then retry once with the new token. |
| [organization_not_selected](https://www.shortsintel.com/docs/reference/errors/organization_not_selected) | 403 | No | Re-authorize the connection and choose an organization. |
| [organization_access_revoked](https://www.shortsintel.com/docs/reference/errors/organization_access_revoked) | 403 | No | Re-authorize against an organization the user still belongs to. |
| [connection_revoked](https://www.shortsintel.com/docs/reference/errors/connection_revoked) | 401 | No | Re-authorize the connection; the old token will not work again. |
| [forbidden](https://www.shortsintel.com/docs/reference/errors/forbidden) | 403 | No | Ask an organization owner or admin to do this, or to grant the role. |
| [key_scope_insufficient](https://www.shortsintel.com/docs/reference/errors/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](https://www.shortsintel.com/docs/reference/errors/invalid_request) | 400 | No | Fix the field named in `detail`, then send the corrected request. |
| [unsupported_platform](https://www.shortsintel.com/docs/reference/errors/unsupported_platform) | 400 | No | Use a platform this operation lists as supported. |
| [unsupported_kind](https://www.shortsintel.com/docs/reference/errors/unsupported_kind) | 422 | No | Do not repeat this request; nothing was charged. Use an operation that serves this kind. |
| [kind_deprecated](https://www.shortsintel.com/docs/reference/errors/kind_deprecated) | 400 | No | Track the Creator, a Hashtag or a Sound instead of a Video. |
| [focus_unsupported_kind](https://www.shortsintel.com/docs/reference/errors/focus_unsupported_kind) | 422 | No | Send the Tracker without `focus`, or pick a kind in `supported_kinds`. |
| [feature_unavailable](https://www.shortsintel.com/docs/reference/errors/feature_unavailable) | 422 | No | Send the request without the switched-off option (for a video, drop `download` from `include`). |
| [video_too_long](https://www.shortsintel.com/docs/reference/errors/video_too_long) | 422 | No | Pick a video under `max_duration_seconds`; this one will never qualify. |
| [not_analysable](https://www.shortsintel.com/docs/reference/errors/not_analysable) | 422 | No | Read the Ad itself instead; a text Ad or one with no readable media never gets an analysis. |
| [not_found](https://www.shortsintel.com/docs/reference/errors/not_found) | 404 | No | Check the id or handle; list your resources to find the right one. |
| [comment_not_found](https://www.shortsintel.com/docs/reference/errors/comment_not_found) | 404 | No | Read the video's comments page first and pass one of its item ids as `comment_id`. |
| [idempotency_conflict](https://www.shortsintel.com/docs/reference/errors/idempotency_conflict) | 409 | No | Resend the original payload with this key, or use a new key for the new payload. |
| [run_not_ready](https://www.shortsintel.com/docs/reference/errors/run_not_ready) | 409 | Yes | Poll the Run until it settles, then read again. If it failed, start a new Run. |
| [advertiser_ambiguous](https://www.shortsintel.com/docs/reference/errors/advertiser_ambiguous) | 409 | No | Ask again with one of `candidates`' `page_id`, `advertiser_id` or `url`. |
| [collection_kind_mismatch](https://www.shortsintel.com/docs/reference/errors/collection_kind_mismatch) | 409 | No | Add this target to a Collection of its own kind. |
| [collection_name_taken](https://www.shortsintel.com/docs/reference/errors/collection_name_taken) | 409 | No | Use the Collection in `collection_id`, or pick another name. |

### Money

| Code | HTTP | Retryable | Action |
| --- | --- | --- | --- |
| [insufficient_balance](https://www.shortsintel.com/docs/reference/errors/insufficient_balance) | 402 | No | Tell the Customer to top up the Balance, then repeat the same request. |
| [max_credits_exceeded](https://www.shortsintel.com/docs/reference/errors/max_credits_exceeded) | 402 | No | Narrow the call until `estimate_credits` fits, or raise `max_credits` if the Customer allows. |
| [key_spend_cap_exceeded](https://www.shortsintel.com/docs/reference/errors/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](https://www.shortsintel.com/docs/reference/errors/rate_limit_exceeded) | 429 | Yes | Wait `retry_after_seconds`, then retry the same request. |
| [concurrency_limit_exceeded](https://www.shortsintel.com/docs/reference/errors/concurrency_limit_exceeded) | 429 | Yes | Wait `retry_after_seconds` for a running Run to finish, then retry. |
| [tracker_limit_exceeded](https://www.shortsintel.com/docs/reference/errors/tracker_limit_exceeded) | 409 | No | Pause or delete a Tracker, then retry. |
| [collection_limit_exceeded](https://www.shortsintel.com/docs/reference/errors/collection_limit_exceeded) | 409 | No | Delete a Collection you no longer use, then retry. |
| [webhook_limit_exceeded](https://www.shortsintel.com/docs/reference/errors/webhook_limit_exceeded) | 409 | No | Delete an endpoint you no longer deliver to, then retry. |
| [webhook_rotation_in_progress](https://www.shortsintel.com/docs/reference/errors/webhook_rotation_in_progress) | 409 | Yes | Wait until `overlap_expires_at`, then rotate again. |

### Upstream and ours

| Code | HTTP | Retryable | Action |
| --- | --- | --- | --- |
| [media_unavailable](https://www.shortsintel.com/docs/reference/errors/media_unavailable) | 502 | No | Tell the Customer the video is deleted, private or blocked; pick another. |
| [vendor_error](https://www.shortsintel.com/docs/reference/errors/vendor_error) | 502 | Yes | Retry with a backoff; nothing was charged. |
| [source_unavailable](https://www.shortsintel.com/docs/reference/errors/source_unavailable) | 503 | Yes | Wait `retry_after_seconds`, then retry; do not treat this as an empty result. |
| [service_unavailable](https://www.shortsintel.com/docs/reference/errors/service_unavailable) | 503 | Yes | Wait `retry_after_seconds`, then retry; nothing was charged. |
| [internal_error](https://www.shortsintel.com/docs/reference/errors/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](https://www.shortsintel.com/docs/concepts/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

```json
{
  "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`.

```json
{
  "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](https://www.shortsintel.com/docs/concepts/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](https://www.shortsintel.com/docs/concepts/runs) 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

```json
{
  "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.
