> ## Documentation Index
> Fetch the complete documentation index at: https://api-tools.memories.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors & Rate Limits

> Error response shape, status codes, rate limits, and quotas for the Video Datalake.

## Error responses

Every non-`2xx` response uses one structured envelope:

```json theme={null}
{ "error": {
  "code": "invalid_argument",
  "message": "an actionable explanation",
  "request_id": "req_xxx",
  "retry_after": null,
  "details": [ { "field": "fps", "code": "out_of_range", "message": "allowed range: [0.1, 30]" } ]
} }
```

The `message` is written to be **actionable** — surface it directly. Include `request_id` in any bug report.

| code                        | HTTP                | When                                                              | Client handling                       |
| --------------------------- | ------------------- | ----------------------------------------------------------------- | ------------------------------------- |
| `invalid_argument`          | 400                 | Missing / wrong-type / out-of-range param                         | Fix per `details`; do not retry as-is |
| `unauthorized`              | 401                 | Missing / invalid key                                             | Check the key                         |
| `forbidden`                 | 403                 | Scope / read-only limit; face switch off                          | Swap key or adjust collection config  |
| `not_found`                 | 404                 | Resource missing / not yours                                      | Do not retry                          |
| `conflict`                  | 409                 | Idempotency / state conflict (cross-model move, double cancel, …) | Handle per `message`                  |
| `video_not_ready`           | 409 + `Retry-After` | Derived content requested before indexing finished                | Back off per `Retry-After`            |
| `quota_exceeded`            | 402                 | Insufficient balance                                              | Top up and retry                      |
| `unsupported_media`         | 415                 | Unsupported file format                                           | Change format                         |
| `payload_too_large`         | 413                 | Search image over 10 MB                                           | Compress the image                    |
| `embedding_mismatch`        | 400                 | Search BYO vector dim ≠ collection model                          | Use 3072-dim vectors (OmniRetriever)  |
| `index_version_unavailable` | 400                 | Search cursor's index version expired                             | Drop the cursor and re-query          |
| `source_unresolved`         | 422                 | Direct-link fetch failed / platform link unsupported              | Use a direct link                     |
| `rate_limited`              | 429 + `Retry-After` | Throttled                                                         | Back off per `Retry-After`            |
| `unavailable`               | 503 + `Retry-After` | Dependency temporarily down / maintenance                         | Back off and retry                    |
| `internal`                  | 500                 | Unexpected error                                                  | Report with `request_id`              |

**Retryable vs not:** auto-retry (respect `Retry-After`) `rate_limited` · `unavailable` · `video_not_ready`; do **not** retry without changing the request `invalid_argument` · `not_found` · `conflict`.

## HTTP status codes

| Status | Meaning                                                                  |
| ------ | ------------------------------------------------------------------------ |
| `200`  | Success                                                                  |
| `202`  | Accepted — an async operation started (poll it, or wait for the webhook) |
| `400`  | Invalid request                                                          |
| `401`  | Missing / invalid key                                                    |
| `403`  | Forbidden (scope, or a disabled feature)                                 |
| `404`  | Not found                                                                |
| `409`  | Conflict — includes `video_not_ready` (with `Retry-After`)               |
| `413`  | Payload too large                                                        |
| `415`  | Unsupported media type                                                   |
| `422`  | Unprocessable — e.g. `source_unresolved`                                 |
| `429`  | Rate limited (`Retry-After`)                                             |
| `500`  | Internal error                                                           |
| `503`  | Temporarily unavailable (`Retry-After`)                                  |

## Rate limits

* `X-RateLimit-Limit / -Remaining / -Reset` headers on every response.
* **Search: 5 QPS/user.**
* Rolling 2-hour concurrent-indexing cap.
* Always respect `Retry-After` on `429` / `503`.

## Limits & quotas

| Item                   | Limit                                                                                                                           |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `fps`                  | 0.1 – 30 (default 1.0)                                                                                                          |
| List `limit`           | 1 – 100 (default 20)                                                                                                            |
| Person reference faces | 1–20 per call; ≤15 MB each; jpg / jpeg / png / webp / bmp                                                                       |
| Video containers       | mp4, m4v, mov, mkv, webm, avi, flv, f4v, wmv, mpg, mpeg, 3gp, ts, m2ts                                                          |
| `callback_url`         | HTTPS, ≤512 chars                                                                                                               |
| `Idempotency-Key`      | ≤128 chars                                                                                                                      |
| Resumable session      | 24h valid, 16 MiB chunks                                                                                                        |
| Signed-URL TTL         | clip cache 5h; details `source_url` / face image 24h; search thumbnail 15 min; `search/images` 1h                               |
| Moment `ref`           | `start ≥ 0`, `end > start`, `end ≤ duration + 1s`                                                                               |
| Search                 | 5 QPS/user; `top_k` ≤ 200; `query_images` ≤ 10; search image ≤ 10 MB; filter nesting ≤ 32 levels; hybrid mode does not paginate |
| Streams                | pull-only (rtsp / rtmp / http); fps 0.1–30 (default 1.0)                                                                        |