Errores

Todo error, en toda ruta y en todo status, tiene el mismo cuerpo:

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

No existe mensaje en texto. El servidor no conoce el idioma de tu usuario, y el texto no se trata en un switch: traduce el code en tu interfaz.

Status HTTPCopy Anchor Link

ValidaciónCopy Anchor Link

Un cuerpo o query fuera del schema responde VALIDATION_ERROR, y extra.errors lista los campos que fallaron, con punto entre los niveles:

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

Ruta inexistenteCopy Anchor Link

Una ruta que no existe responde 404 NOT_FOUND, con extra.openapi apuntando a la especificación y extra.docs al llms.txt de esta documentación. Así un agente que adivinó la ruta encuentra el camino correcto.

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

Error de jobCopy Anchor Link

Un job que falla después de ser aceptado no devuelve un status HTTP de error: la ruta de lectura responde 200 con status: "failed" y el motivo en error_code. En el clipping, por ejemplo, DOWNLOAD_PRIVATE_VIDEO indica que el video quedó privado después del análisis. Ve Clips.

Catálogo de códigosCopy Anchor Link

Todos los códigos que devuelve la API, generados a partir de la especificación en cada publicación de esta documentación. Para el significado de un código en una ruta, abre la ruta en la referencia.