Erros

Todo erro, em toda rota e em todo status, tem o mesmo corpo:

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

Não existe mensagem em texto. O servidor não sabe o idioma do seu usuário, e texto não se trata em switch: traduza o code na sua interface.

Status HTTPCopy Anchor Link

ValidaçãoCopy Anchor Link

Corpo ou query fora do schema responde VALIDATION_ERROR, e extra.errors lista os campos que falharam, com ponto entre os níveis:

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

Rota inexistenteCopy Anchor Link

Um caminho que não existe responde 404 NOT_FOUND, com extra.openapi apontando para a especificação e extra.docs para o llms.txt desta documentação. É assim que um agente que chutou a rota encontra o caminho certo.

Tratando errosCopy 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);
	}
}

Erro de jobCopy Anchor Link

Um job que falha depois de aceito não devolve status HTTP de erro: a rota de leitura responde 200 com status: "failed" e o motivo em error_code. Na clipagem, por exemplo, DOWNLOAD_PRIVATE_VIDEO diz que o vídeo ficou privado depois da análise. Veja Clipagem.

Catálogo de códigosCopy Anchor Link

Todos os códigos que a API devolve, gerados da especificação a cada publicação desta documentação. Para o significado de um código numa rota, abra a rota na referência.