> ## Documentation Index
> Fetch the complete documentation index at: https://docs.perceptron.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# Egocentric limits and errors

> Prepare valid inputs, pace requests, and distinguish request errors from failed jobs.

Start with the [egocentric workflow](https://docs.perceptron.inc/services/egocentric.md) 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`:

```json theme={null}
{
  "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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.