Errors & Rate Limits - Memories.ai API

Error responses

Every non-2xx response uses one structured envelope:

{ "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)