Saltearse al contenido

Errores y reintentos

Los errores comerciales devuelven code y message en el nivel superior del cuerpo de la respuesta. detail suele ser igual que message, pero puede ser una explicación diferente y más breve (como se muestra a continuación); muestre message a los usuarios. Los mensajes están en chino:

{
"code": "CONCURRENCY_LIMITED",
"message": "排队中的文件已达上限(1000 个),请等部分文件翻译完成后再提交",
"detail": "排队文件完成一部分后可继续提交"
}

Algunos errores comerciales devuelven únicamente code. Los fallos de validación devuelven 422 junto con una lista de errores de campo en detail:

{
"detail": [
{ "loc": ["body", "target_lang"], "msg": "Field required", "type": "missing" }
]
}

Trate los errores primero por el estado HTTP y luego por code: muchos errores devuelven únicamente el genérico UNKNOWN_ERROR, y solo algunos incluyen un code específico (como los 429 casos que se muestran a continuación). Registre la cabecera de respuesta X-Request-Id para la resolución de problemas.

EstadoSignificadoConsejo
400Solicitud no válida; por ejemplo, la configuración seleccionada no está disponible.Corrija la solicitud; no vuelva a intentarlo
401Credencial faltante, no válida, caducada o revocadaCambiar las credenciales
402El saldo (después de deducir la deuda) no supera el umbral del trabajo, o es negativo; con una clave API, el presupuesto restante de la clave podría ser demasiado bajo.Recargue (o aumente el presupuesto de la clave) y vuelva a enviarlo.
403Los límites de la clave no permiten esta operación (por ejemplo, la configuración de traducción no está permitida), la cuenta está deshabilitada o la operación debe realizarse en un navegador con sesión iniciada (como al gestionar claves API).Verifique la configuración clave o utilice el sitio web
404El recurso no existe, fue eliminado o pertenece a otra cuenta (los tres casos se ven iguales)Verifique el ID
409La clave de idempotencia se utilizó para una solicitud diferente, o el estado del recurso no permite la operación.Consulte la operación original y luego decida
410El recurso o punto final ha desaparecido de forma permanente; por ejemplo, un punto final retirado o un trabajo eliminado asociado a una clave de idempotencia.No volver a intentarlo
413El archivo o el cuerpo de la solicitud supera el límiteUtilice un archivo más pequeño
415Formato de archivo no compatibleUtilice otro formato
422La validación falló, o el archivo está vacío o no contiene nada que procesar.Corrija los campos; no vuelva a intentarlo automáticamente
429Tasa, tamaño de la cola o presupuesto limitadosVéase a continuación
5xxError temporal del servicioRetraso exponencial con un número máximo de intentos
codeSignificadoQué hacer
RATE_LIMITEDDemasiadas solicitudesEspere a Retry-After y luego vuelva a intentarlo
CONCURRENCY_LIMITEDHay demasiados trabajos de traducción de archivos en la colaEspere a Retry-After o a que algunos trabajos finalicen
AUTH_API_KEY_QUOTA_EXCEEDEDEl presupuesto de la clave se ha agotadoNo vuelva a intentarlo hasta que se aumente el presupuesto

Un 429 sin Retry-After debe gestionarse mediante retroceso exponencial.

  • Las consultas pueden reintentarse directamente.
  • Al volver a intentar una solicitud de creación, reutilice el mismo Idempotency-Key y exactamente el mismo cuerpo; utilice una nueva clave para cada nuevo envío.
  • Tras una carga fallida, solicite una nueva dirección de carga.
  • Establezca los tiempos de espera de conexión, lectura y total para cada solicitud, añada una variación aleatoria a los reintentos y limite el número de intentos.
import random
import time
for attempt in range(5):
response = call_api()
if response.status_code not in {429, 500, 502, 503, 504}:
break
if response.status_code == 429 and response.json().get("code") == "AUTH_API_KEY_QUOTA_EXCEEDED":
break
retry_after = response.headers.get("Retry-After")
delay = float(retry_after) if retry_after else min(2 ** attempt, 16)
time.sleep(delay + random.random())