Egocentric limits and errors

Start with the egocentric workflow for submission, polling, and result downloads.

Input requirements

Submit 1–1,000 videos in a JSON request body no larger than 8 MiB, with Content-Type: application/json. Each input uses type: "video_url" and a video_url.url string containing an HTTP(S) URL of at most 4,096 characters. Serve the video directly at a publicly reachable address. A successful 202 response accepts the batch; URL access checks and media validation happen afterward and can fail individual jobs. Each video must be no larger than 512 MiB and no longer than 30 minutes. An unreadable, oversized, or overlong video fails with video_invalid. Supported container families are the MP4 family (including MP4, MOV, and 3GP), Matroska/WebM, and AVI. The file must contain a readable video stream; a filename extension alone does not establish that the video is valid. Private or loopback addresses and URLs containing a username or password are not supported. These links can be accepted initially, but jobs using them can later fail with video_invalid. A video_unavailable error means the video download could not be completed. Check the job’s error for its failure details. An optional filename must contain 1–255 characters, without path separators or control characters, and cannot be . or ... Omit optional fields instead of sending null. Unknown fields and duplicate JSON keys are rejected.

Request and submission limits

Your organization’s API keys share request limits. Submit requests and read requests have separate limits. Every POST attempt counts, including an idempotent replay or an invalid submission. Lists, status reads, and result downloads all count as reads; dashboard batch and job reads share that read allowance. The limits below are defaults; your organization’s limits may differ.

Limit	Default
Submit requests	150 per organization per minute.
Read requests	600 per organization per minute.
Newly accepted jobs	1,000 per organization in a rolling 24-hour period.
Queued jobs	1,000 per organization.

Submission capacity also limits the number of new jobs accepted. A batch can fit within the 1,000-input request limit and still receive 429 with capacity_exceeded when insufficient capacity remains. Pace new submissions and polling across your applications, and use Retry-After when it is returned.

Handle HTTP errors

An HTTP request failure uses an error object. For example, an invalid batch input count returns 400:

{
  "error": {
    "message": "Must contain between 1 and 1000 inputs.",
    "type": "invalid_request_error",
    "param": "inputs",
    "code": "invalid_request_error"
  }
}

Use both the HTTP status and error.code to choose an action. error.param identifies the relevant field when available; some fields, including code, can be null.

HTTP status	`error.code`	Action
`400`	`invalid_request_error`	Correct the body, header, or query field identified by `param`.
`401`	`authentication_error`	Supply a valid API key in the bearer header.
`404`	`null`	Check the resource ID and that the API key belongs to its organization.
`409`	`idempotency_conflict`	Reuse the original request with this key, or use a new key for a new submission.
`409`	`result_unavailable`	Check the job: continue polling if unfinished; inspect its error if failed.
`410`	`result_expired`	The completed result is no longer available for download.
`413`	`request_too_large`	Reduce the JSON request body to 8 MiB or less.
`429`	`rate_limit_error`	Pace requests across the organization and wait for `Retry-After`.
`429`	`capacity_exceeded`	Wait for `Retry-After` before attempting another submission.
`429`	`insufficient_quota`	Resolve the organization’s credit balance before submitting again. This response has no `Retry-After`.
`500`	`server_error`	Retry with backoff; preserve the original key and body for a submission.
`503`	`service_unavailable` or `operation_paused`	Wait for `Retry-After` before retrying. Preserve the original key and body for a submission.

Retry-After is a delay in seconds, not a promise that the next request will succeed. Apply a retry limit and an overall deadline in your application. Result downloads can fail after a 200 response has begun; check for a complete, valid JSON download as well as the HTTP status.

Read job failures

A successful HTTP 200 response from a job endpoint can describe a failed job. When status is failed, the job’s error contains code, message, fault, and retryable. This object has a different structure from an HTTP request error.

fault: "user_error" identifies an input or account problem.
fault: "system_error" identifies a service failure.
retryable: true means the same input could succeed in a new submission after the cause is resolved.

Do not infer retryability from an HTTP status or the fault category alone. Read the returned job error, and allow for future error codes.

Retry requests and failed jobs

For a lost submit response or a temporary request failure, repeat the original request with its original idempotency key. If it was already accepted, the API returns the existing batch. A replay cannot restart a failed job. Failed jobs are not automatically rerun. To try a failed input again, resolve the reported cause, select the inputs you want to retry, and create a new batch with a new idempotency key. Check retryable before deciding whether unchanged input is appropriate; it does not guarantee success. Avoid resubmitting completed inputs unintentionally, since a new batch creates new jobs.

Services

Detect

Egocentric

Egocentric limits and errors

Input requirements

Request and submission limits

Handle HTTP errors

Read job failures

Retry requests and failed jobs

​Input requirements

​Request and submission limits

​Handle HTTP errors

​Read job failures

​Retry requests and failed jobs

Input requirements

Request and submission limits

Handle HTTP errors

Read job failures

Retry requests and failed jobs