Errores y límites

Los errores llegan como application/problem+json (RFC 9457), siempre con la misma forma:

{
  "type": "https://developer.translaqe.com/errors/invalid-request",
  "title": "La petición no es válida",
  "status": 400,
  "errors": [
    { "path": "target_lang", "message": "El idioma de origen y el de destino deben ser distintos" }
  ]
}

• type identifica el error y es la dirección de su explicación en esta página. Distingue los errores por la última parte de type (invalid-request), nunca por title.
• title y detail son para personas. Por ahora llegan en español.
• errors aparece cuando la petición no es válida y nombra cada campo que está mal.
• La cabecera X-Request-Id identifica la petición: guárdala junto al error.

Cuándo reintentar

Estado	¿Reintentar?
400, 401, 403, 404, 409, 413, 422	No. Hay que cambiar la petición, o aquello de lo que habla tiene que estar en otro estado.
402	No. El plan no lo permite: mira GET /v1/plan.
429	Sí, pasados los segundos que dice Retry-After.
502, 503	Sí, con esperas cada vez más largas: 1, 2, 4, 8 segundos.
500	Una vez. Si se repite, escríbenos con el X-Request-Id.

# --retry repeats on 429 and 5xx, waiting what Retry-After says.
curl --retry 4 --retry-max-time 120 https://api.translaqe.com/v1/translate \
  -H "Authorization: Bearer $TRANSLAQE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source_lang": "es", "target_lang": "en", "segments": ["Hola."]}'

Subir un documento se puede repetir sin miedo si mandas una Idempotency-Key: el mismo valor devuelve el mismo trabajo.

Tipos de error

invalid-request

400. Falta un campo o está mal: errors dice cuál. Corrige la petición.

invalid-language

400. Un código de idioma no está en el catálogo. GET /v1/languages da los que se pueden usar.

unauthorized

401. Falta la clave, está mal escrita o se ha revocado. Manda Authorization: Bearer <tu clave>.

forbidden

403. La clave vale, pero no puede hacer esto.

trial-ended

402. La prueba gratuita ha terminado. Tus documentos y tus recursos siguen ahí; para seguir traduciendo hace falta el plan de pago.

quota-exceeded

402. Al plan le quedan menos caracteres de los que pide la petición. detail dice cuántos quedan.

trial-paused

503. Las pruebas gratuitas están en pausa hasta el día 1 del mes que viene. A los planes de pago no les afecta.

rate-limited

429. Más de 120 peticiones en un minuto con la misma clave. Espera lo que dice Retry-After.

translation-failed

422. Ningún modelo ha dado una traducción válida de alguna frase; errors dice cuáles. Repetir la petición da el mismo resultado: quítalas o cámbialas.

engine-unavailable

503. El motor de traducción no responde. Prueba dentro de un momento.

engine-mismatch

502. El motor ha respondido algo que no cuadra con lo pedido. Prueba otra vez.

qe-unavailable

503. El servicio que pone la nota no responde. Prueba dentro de un momento, o traduce con qe: false.

invalid-document

400. El documento no se puede traducir: su formato no es de los admitidos.

document-rejected

400 o 413. El fichero se ha rechazado: está vacío (400) o pesa más de 50 MB (413).

job-not-found

404. No hay ningún trabajo con ese id en tu organización.

job-not-ready

409. El trabajo no tiene fichero traducido: no ha terminado, o ha fallado.

job-busy

409. El trabajo está en cola o en marcha, y lo que pides necesita que haya acabado. Espera, o cancélalo antes.

segment-not-found

404. El documento no tiene ninguna frase en esa posición.

segment-locked

409. La frase está bloqueada y no se puede cambiar.

invalid-segment

400. La corrección no vale: lo normal es que no lleve las mismas marcas de formato que el origen.

invalid-resource

400. La memoria o el glosario no se puede crear: el formato del fichero, el nombre o los idiomas están mal.

resource-not-found

404. No hay ninguna memoria ni ningún glosario con ese id en tu organización.

resource-busy

409. La memoria o el glosario todavía se está indexando. Espera a que su estado sea ready.

resource-language-mismatch

400. Una memoria o un glosario es de otro par de idiomas que la petición.

entry-not-found

404. La memoria o el glosario no tiene ninguna entrada con ese id.

invalid-entry

400. La entrada no vale: está vacía o es demasiado larga.

project-not-found

404. No hay ningún proyecto con ese id en tu organización.

invalid-project

400. El nombre del proyecto no vale.

request-not-found

404. No hay ninguna petición con ese id en tu organización.

not-found

404. La ruta no existe.

storage-unavailable

503. Un servicio de detrás de la API no responde. Lo mismo vale para store-unavailable y usage-unavailable. Prueba dentro de un momento.

internal

500. Algo ha fallado por nuestra parte. Escríbenos con el X-Request-Id.

Límites

Qué	Límite
Peticiones por clave	120 por minuto
Frases por POST /v1/translate	50
Caracteres por frase	2.000
Caracteres por POST /v1/translate	10.000
Traducciones por POST /v1/qe	100
Memorias o glosarios nombrados en una petición	20 de cada
Tamaño de un fichero (documentos, memorias, glosarios)	50 MB
Periodo de una consulta a GET /v1/usage	1 año