Errores y límites de la API

Esta página documenta el formato de error, la lista completa de códigos de respuesta, los límites de solicitud y cómo el uso del plan afecta la traducción.

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á habilitado para tu sitio.
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.
PLAN_LIMIT_REACHED	403	Se agotó la cuota de palabras de tu plan.
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.

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

Si el cuerpo excede los 5 MB, recibirás REQUEST_TOO_LARGE (413). Para páginas grandes o conjuntos de cadenas extensos, divide el trabajo en varias solicitudes.

Cuerpos de solicitud comprimidos

El Traductor acepta cuerpos de solicitud comprimidos con gzip. Establezca la cabecera Content-Encoding a gzip y envíe el JSON comprimido; el cuerpo se descomprime antes de analizarlo. Esto es útil para documentos HTML grandes que se acercan al límite de 5 MB.

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 consume la asignación de palabras de su plan, compartida entre los puntos de conexión HTML y de cadenas. El uso se aplica por solicitud en lugar de rechazar toda la llamada:

• Si su asignación se agota antes de que llegue una solicitud, la solicitud falla con PLAN_LIMIT_REACHED (403).
• Si la asignación se agota a mitad de una solicitud, Universally traduce tanto como puede, devuelve una respuesta exitosa e informa el déficit en los metadatos.

Dos campos de metadatos describen esto:

Campo	Significado
limitReached	true cuando se alcanzó la asignación de palabras durante la solicitud.
skippedStrings	El número de cadenas que quedan en el idioma de origen porque se alcanzó el límite.

Cuando limitReached es true, trate la respuesta como parcial: se devuelve contenido traducido donde sea posible y las cadenas no traducidas vuelven a su texto original. Actualice su plan para aumentar la asignación.

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.