Errors & limits

Two things make error handling here mechanical rather than defensive. Every error has the same shape, and every error has a code that does not change. Write your handling against code and status, and the only thing left to decide is whether to wait, fix the request, or stop.

The problem document#

Errors are served as application/problem+json with five members. There is no nested error object anywhere in the API, and never has been:

HTTP/1.1 422 Unprocessable Entity
content-type: application/problem+json
x-ratelimit-remaining: 58

{
  "type": "https://anjin.media/errors/invalid_settings",
  "title": "Invalid Settings",
  "status": 422,
  "detail": "target_duration_s: required integer in [10, 600]",
  "code": "invalid_settings"
}

Some problems carry extension members alongside the five - extra facts about that particular failure. They sit at the top level and can never overwrite a reserved member, so a parser that reads the five and ignores the rest is always correct:

{
  "gate": "render",
  "limit": 3,
  "in_flight": 3,
  "requested": 1,
  "type": "https://anjin.media/errors/concurrency_limit",
  "title": "Concurrency Limit",
  "status": 429,
  "detail": "too many concurrent render operations - 3 in flight, 1 requested, limit 3",
  "code": "concurrency_limit"
}

Every code#

Grouped by status. This is the complete list - a response from this API carries one of these codes or it is a bug.

400, 401, 403 and 404

{
  "type": "https://anjin.media/errors/insufficient_scope",
  "title": "Insufficient Scope",
  "status": 403,
  "detail": "this API key lacks the required \"admin\" scope",
  "code": "insufficient_scope"
}

409 - the object is busy or in the wrong state

Six codes, and all of them mean the request was well formed and arrived at the wrong moment. None of them is fixed by changing the body:

422 - the request cannot be processed

Eight codes. These are all fixable by you, and every detail names the field or the value that failed:

429 - too much at once

Six codes across three different mechanisms: request rate, work in flight, and account-level ceilings. All six carry retry-after:

402 - billing refusals

Two codes belong to the source-minutes gate, which meters footage once, at ingest, and never at planning or rendering: minutes_plan_required and minutes_allowance_exhausted. Both are raised only by POST /v1/source-groups, and only where the platform has the gate enabled - so whether a given environment can produce them is not something this page can assert. Handle them the way you would any refusal you cannot retry your way out of: surface it to a person, stop the loop, and do not re-send. What each one means:

• minutes_plan_required - the account has no plan and no live trial. Carries upgrade_url.
• minutes_allowance_exhausted - the account's source-minute allowance for the current period is used up. The gate refuses when the period's usage is already at or over the allowance, so one group can overshoot and the next create is refused. Carries allowance, used (to one decimal), period_end (ISO 8601, when the allowance resets) and upgrade_url. Nothing already ingested is affected, and renders of existing cuts still run.

One code belongs to the camera entitlement, checked when a group is created with two or more camera files:

• multicam_not_entitled - the group carries more camera files than the plan allows: one on Creator and Pro, two on Studio, four on Enterprise. The camera count is fixed at creation and never re-checked. Raised only where billing enforcement is on.

Two codes remain for legacy credit accounts only. An account on a published plan, an Enterprise contract or a live trial is never refused by the credit ladder:

• insufficient_credits - the account balance will not cover more work.
• account_read_only - the account can still read everything it owns and cannot start new work.

Pricing is where the commercial model lives; this page describes only the shape of the refusal.

500 and 503

Rate limits#

Two token buckets apply to every authenticated request, and they refill continuously rather than resetting on a clock edge:

• 60 requests a minute per key.
• 120 requests a minute per account, across every key it holds - minting more keys does not buy throughput.

Every authenticated response carries x-ratelimit-remaining, which is whichever of the two buckets is lower. The per-key check runs first and short-circuits, so a request refused per-key never also spends an account token:

x-ratelimit-remaining: 0
retry-after: 3

The two 429s carry different codes on purpose. If you are seeing account_rate_limited while one key looks idle, the traffic is coming from elsewhere on the same account. Authentication covers key hygiene, which is usually the real fix.

Which responses carry retry-after

Concurrency ceilings#

Separate from request rate: these bound how much work one account can have running at once. They exist so that one busy account cannot monopolise the workers, and they are checked before anything is written, so a refusal never leaves a half-started job behind.

The test is in flight + requested > limit, not in flight ≥ limit. A render batch is admitted whole or not at all, which is why a three-aspect batch cannot start with two places available:

{
  "gate": "plan",
  "limit": 2,
  "in_flight": 2,
  "requested": 1,
  "type": "https://anjin.media/errors/concurrency_limit",
  "title": "Concurrency Limit",
  "status": 429,
  "detail": "too many concurrent plan operations - 2 in flight, 1 requested, limit 2",
  "code": "concurrency_limit"
}

The extension members are the useful part - gate tells you which queue you are on, in_flight and limit tell you how far over you are. Wait for the work you already have to finish; five seconds is the suggested first look.

Pagination#

List endpoints are keyset-paginated, newest first. Two parameters, and one field in the response:

• limit - how many rows, default 50, maximum 100. A larger number is clamped to 100; anything that is not a positive integer falls back to 50. Neither case is an error.
• cursor - an opaque token from the previous page.
• next_cursor - in the response body, or null on the last page. Follow it until it is null; do not try to compute the next one.

curl -sS "https://anjin-media-api.fly.dev/v1/source-groups?limit=25" \
  -H "authorization: Bearer $ANJIN_API_KEY"

CURSOR=MjAyNi0wOC0xNlQwOTo0MTo1NS4wMTdafDJiOGU0ZjAxLTlkNjMtNGE1Ny1iMWMwLThlNWEzN2Q2NGY5Mg

curl -sS "https://anjin-media-api.fly.dev/v1/source-groups?limit=25&cursor=$CURSOR" \
  -H "authorization: Bearer $ANJIN_API_KEY"

Cursors are values rather than positions, so a row inserted while you are walking the list cannot shift a page under you or make you read the same row twice. Treat the token as opaque: it encodes a timestamp and an id today, and that is free to change.

One endpoint is not paginated: GET /v1/cuts/:id/renders returns every render a cut has, in one response, because a cut has a handful and never a thousand.

Idempotency#

Send an idempotency-key header on any write you might retry. The header is honoured on these routes:

It is deliberately not honoured on PATCH /v1/cuts/:id/plan: that call is synchronous, calls no planner, and has nothing to duplicate.

What a key identifies

The whole request - method, path and a hash of the body - scoped to your account. Two different calls can therefore use the same key string without colliding, and the same call retried with the same key is recognised however long it has been.

Claim before execute

The key is claimed before the handler runs, not after. That ordering is the whole point: a read-then-write would leave a window in which two concurrent retries both started a planner run.

• Replay. Once the original finished with a 2xx, that response is stored. A retry with the same key gets the stored body and status, with idempotency-replayed: true on the response.
• A different body, same key. 422 idempotency_conflict. Nothing is overwritten and nothing runs.
• A duplicate arriving while the first is in flight. It waits, polling, for up to two seconds. If the winner finishes inside that budget, the duplicate gets the winner's response - a replay, not an error. If the budget expires first, it gets 409 idempotency_in_progress.

What is stored, and what is not

• Only 2xx responses are stored. A replay never serves a cached error.
• A 4xx releases the key immediately. The request was refused before anything committed, so fixing the body and retrying with the same key works.
• A 5xx holds the key. The handler may have committed and then failed, and releasing would let a retry duplicate whatever it committed. The claim clears itself on a sweep - allow roughly three minutes - during which a retry gets 409 idempotency_in_progress. That is the trade: a bounded delay instead of a second copy of whatever already committed.
• Secrets are redacted from the stored copy. Registering a webhook endpoint returns a secret once; a replay of that create returns the same shape without it. The caller who needed it already has it.

HTTP/1.1 202 Accepted
idempotency-replayed: true
content-type: application/json

Recovering#

Four patterns cover nearly everything. The status tells you which one you are in.

409 busy - poll, do not retry

Something already holds the object. Retrying the same call in a tight loop just produces more 409s. Read the object instead - GET /v1/cuts/:id and wait for status to leave planning or rendering - and act when it has. Poll on the order of seconds, not milliseconds, and prefer webhooks, which remove the loop entirely.

429 - back off on retry-after

Sleep for the number of seconds in the header, then retry the identical request. All six 429s carry it, and it is a real figure rather than a constant: for a rate limit it is when a token exists again, for a concurrency ceiling it is five seconds, for an account ceiling it is the end of the window. Add a little jitter if several workers share a key, or they will all wake together.

503 - wait, then repeat

Nothing was started. Wait for retry-after and send the same request again.

5xx with an idempotency key - wait out the hold

A 500 is the one case where you cannot tell from the outside whether the work committed. Retry with the same idempotency-key and one of two things happens: you get 409 idempotency_in_progress, meaning wait a little longer, or the request runs and you get a real answer. Retrying without a key is what produces two cuts.

Everything on this page is the same whether you call the REST API or the MCP server - the tools return these exact documents as tool errors. Creating a composition lists the codes that one endpoint can produce, and Uploading video the ones ingest produces.