Errors

Every error, on every route and every status, has the same body:

{ "code": "INSUFFICIENT_CREDITS", "extra": { "credits_needed": 121, "current_balance": 40 } }

There is no text message. The server does not know your user's language, and text cannot be handled in a switch: translate the code in your interface.

HTTP statusCopy Anchor Link

ValidationCopy Anchor Link

A body or query outside the schema returns VALIDATION_ERROR, and extra.errors lists the fields that failed, with a dot between levels:

{ "code": "VALIDATION_ERROR", "extra": { "errors": ["video_id", "timeframe.end"] } }

Nonexistent routeCopy Anchor Link

A path that does not exist returns 404 NOT_FOUND, with extra.openapi pointing to the specification and extra.docs to this documentation's llms.txt. That is how an agent that guessed the route finds the right path.

Handling errorsCopy Anchor Link

const response = await fetch(`${API}/clips`, { method: "POST", headers, body });
if (!response.ok) {
	const { code, extra } = await response.json();
	switch (code) {
		case "INSUFFICIENT_CREDITS":
			return askForTopUp(extra.credits_needed);
		case "RATE_LIMIT_EXCEEDED":
		case "SERVICE_UNAVAILABLE":
			return retryAfter(Number(response.headers.get("Retry-After")));
		default:
			throw new Error(code);
	}
}

Job errorCopy Anchor Link

A job that fails after being accepted does not return an error HTTP status: the read route responds 200 with status: "failed" and the reason in error_code. In clipping, for example, DOWNLOAD_PRIVATE_VIDEO says the video became private after the analysis. See Clipping.

Code catalogCopy Anchor Link

All the codes the API returns, generated from the specification on every publication of this documentation. For the meaning of a code on a route, open the route in the reference.