Referencia completa de la API: developer.universally.com contiene la especificación en vivo tanto para la API del Traductor como para la API de Plataforma, con cada campo, código de estado y ejemplo de respuesta. Esta página cubre lo que vale la pena saber al respecto.
Cada respuesta utiliza el mismo sobre, por lo que un cliente se ramifica en el campo code en lugar de solo en el estado HTTP.
Envolvente de respuesta
Cada respuesta, exitosa o de error, utiliza la misma envolvente JSON:
{
"success": false,
"data": null,
"message": "Invalid source URL format.",
"code": "TRANSLATION_INVALID_SOURCE_URL"
}
En caso de error, success es false y data es null. Ramifica según el campo code en lugar del message legible por humanos, que puede cambiar.
Códigos de error
| Código | HTTP | Significado |
|---|---|---|
API_KEY_MISSING |
401 | No se proporcionó la cabecera X-API-Key. |
API_KEY_INVALID_FORMAT |
401 | La clave no tiene un formato reconocido. |
API_KEY_MALFORMED |
401 | La clave no se pudo analizar. |
API_KEY_INVALID |
401 | La clave tiene un formato correcto pero no es reconocida. |
API_KEY_PROJECT_INCOMPLETE |
500 | El sitio vinculado a esta clave está mal configurado. Contacta con soporte. |
PROJECT_NOT_FOUND |
404 | Ningún sitio coincide con esta clave. |
PROJECT_IS_DELETED |
404 | El sitio ha sido eliminado y ya no es accesible. |
TRANSLATION_INVALID_SOURCE_URL |
400 | sourceUrl no es una URL válida. |
TRANSLATION_SOURCE_URL_DOMAIN_MISMATCH |
403 | sourceUrl no coincide con el dominio de tu sitio. |
TRANSLATION_SAME_LANGUAGE |
400 | El idioma de destino es igual al idioma de origen. |
TRANSLATION_TARGET_LANGUAGE_NOT_ALLOWED |
403 | El idioma de destino no está configurado para tu sitio, o enviaste un código de región donde se requería un código de variante. |
TRANSLATION_NO_LANGUAGES_CONFIGURED |
400 | No hay idiomas de destino configurados para el sitio. |
TRANSLATION_SERVICE_UNAVAILABLE |
503 | El servicio de traducción no está disponible temporalmente. Intenta de nuevo con retroceso. |
TRANSLATION_SERVICE_FAILED |
500 | El servicio de traducción no pudo procesar la solicitud. |
NO_TRANSLATABLE_CONTENT |
400 | No se encontró contenido traducible en el HTML. |
VALIDATION_ERROR |
400 | El cuerpo de la solicitud no pasó la validación del esquema. |
INVALID_JSON |
400 | El cuerpo de la solicitud no es un JSON válido. |
DECOMPRESSION_ERROR |
400 | No se pudo descomprimir un cuerpo gzip. |
REQUEST_TOO_LARGE |
413 | El cuerpo de la solicitud excede los 5 MB. |
NOT_FOUND |
404 | Ruta desconocida. |
ERROR_INTERNO_DEL_SERVIDOR |
500 | Error inesperado del servidor. Es seguro reintentar con retroceso. |
Límites de solicitud
| Límite | Valor |
|---|---|
| Cuerpo de solicitud máximo | 5 MB |
| Cadenas máximas por solicitud | 500 (endpoint de cadenas) |
| Métodos permitidos | GET, POST, OPTIONS |
El límite de 5 MB se aplica a los bytes que envías, por lo que un cuerpo comprimido con gzi p se mide comprimido. Si se excede, recibes REQUEST_TOO_LARGE (413). Para páginas grandes o conjuntos de cadenas grandes, comprime el cuerpo o divide el trabajo en varias solicitudes.
Cuerpos de solicitud comprimidos
El Traductor acepta cuerpos de solicitud comprimidos con gzip. Establece la cabecera Content-Encoding en gzip y envía el JSON comprimido; el cuerpo se descomprime antes de analizarlo. Dado que el límite de tamaño cuenta los bytes que envías, la compresión es lo que permite que un documento varias veces más grande que 5 MB sea procesado.
Content-Type: application/json
Content-Encoding: gzip
Si la descompresión falla, la respuesta es DECOMPRESSION_ERROR (400).
Solicitudes de origen cruzado
El Traductor devuelve cabeceras CORS permisivas, permitiendo solicitudes desde cualquier origen con las cabeceras Content-Type, X-API-Key y Content-Encoding. Aun así, las solicitudes transportan su clave de API y deben enviarse del lado del servidor. Consulte Autenticación.
Uso del plan y traducciones parciales
La traducción descuenta el total de palabras de tu plan, compartido entre los puntos de conexión HTML y de cadenas.
Superar el límite no es un error. No hay un código de estado para ello: un espacio de trabajo que excede el límite aún recibe un 200, con el déficit informado en los metadatos. El límite se verifica una vez, cuando llega la solicitud, por lo que una solicitud que comienza por debajo del límite termina todo lo que necesita, incluso si eso la lleva más allá del total.
| Campo | Significado |
|---|---|
limitReached |
true si el espacio de trabajo ya estaba en o por encima de su total de palabras cuando llegó la solicitud. |
skippedStrings |
El número de cadenas que quedaron sin traducir debido a eso. |
Cuando limitReached es true, trata la respuesta como parcial. Todo lo que ya se tradujo todavía se devuelve del almacenamiento; todo lo que habría requerido una nueva traducción no se devuelve. En el punto de conexión HTML, ese texto permanece en el idioma de origen en el documento devuelto. En el punto de conexión de cadenas, esas claves no están presentes en el mapa translations, por lo que recurre a tu propio texto de origen para cualquier clave que no obtengas de vuelta. Consulta Traducir cadenas.
Aumenta el total con un complemento de palabras o un plan más grande. Consulta Límites de uso.
Reintentos
Para errores transitorios (TRANSLATION_SERVICE_UNAVAILABLE en 503, o cualquier 5xx), reintente con retroceso exponencial. Las traducciones se almacenan en caché, por lo que las solicitudes reintentadas que tuvieron éxito parcial anteriormente reutilizan el trabajo existente y solo traducen lo que aún falta. No reintente errores 4xx; indican un problema con la solicitud que no se resolverá por sí solo.