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.
HTTP status
Sección titulada «HTTP status»| Estado | Significado | Consejo |
|---|---|---|
400 | Solicitud no válida; por ejemplo, la configuración seleccionada no está disponible. | Corrija la solicitud; no vuelva a intentarlo |
401 | Credencial faltante, no válida, caducada o revocada | Cambiar las credenciales |
402 | El 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. |
403 | Los 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 |
404 | El recurso no existe, fue eliminado o pertenece a otra cuenta (los tres casos se ven iguales) | Verifique el ID |
409 | La 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 |
410 | El 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 |
413 | El archivo o el cuerpo de la solicitud supera el límite | Utilice un archivo más pequeño |
415 | Formato de archivo no compatible | Utilice otro formato |
422 | La validación falló, o el archivo está vacío o no contiene nada que procesar. | Corrija los campos; no vuelva a intentarlo automáticamente |
429 | Tasa, tamaño de la cola o presupuesto limitados | Véase a continuación |
5xx | Error temporal del servicio | Retraso exponencial con un número máximo de intentos |
Manejo de 429
Sección titulada «Manejo de 429»code | Significado | Qué hacer |
|---|---|---|
RATE_LIMITED | Demasiadas solicitudes | Espere a Retry-After y luego vuelva a intentarlo |
CONCURRENCY_LIMITED | Hay demasiados trabajos de traducción de archivos en la cola | Espere a Retry-After o a que algunos trabajos finalicen |
AUTH_API_KEY_QUOTA_EXCEEDED | El presupuesto de la clave se ha agotado | No vuelva a intentarlo hasta que se aumente el presupuesto |
Un 429 sin Retry-After debe gestionarse mediante retroceso exponencial.
Estrategia de reintento
Sección titulada «Estrategia de reintento»- Las consultas pueden reintentarse directamente.
- Al volver a intentar una solicitud de creación, reutilice el mismo
Idempotency-Keyy 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 randomimport 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())