Errors and limits

Errors come as application/problem+json (RFC 9457), always with the same shape:

{
  "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 identifies the error and is the address of its explanation on this page. Tell errors apart by the last part of type (invalid-request), never by title.
• title and detail are for people. For now they come in Spanish.
• errors appears on an invalid request and names each field that is wrong.
• The X-Request-Id header identifies the request: keep it with the error.

When to retry

Status	Retry?
400, 401, 403, 404, 409, 413, 422	No. The request has to change, or the thing it is about has to be in another state.
402	No. The plan does not allow it: see GET /v1/plan.
429	Yes, after the seconds that Retry-After says.
502, 503	Yes, with growing waits: 1, 2, 4, 8 seconds.
500	Once. If it happens again, write to us with the 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."]}'

Uploading a document is safe to repeat if you send an Idempotency-Key: the same value returns the same job.

Error types

invalid-request

400. A field is missing or wrong: errors lists each one. Fix the request.

invalid-language

400. A language code is not in the catalogue. GET /v1/languages lists the ones you can use.

unauthorized

401. The key is missing, mistyped or revoked. Send Authorization: Bearer <your key>.

forbidden

403. The key is valid but may not do this.

trial-ended

402. The free trial is over. Your documents and resources are still there; to keep translating you need the paid plan.

quota-exceeded

402. The plan has fewer characters left than the request needs. detail says how many are left.

trial-paused

503. Free trials are paused until the first day of next month. Paid plans are not affected.

rate-limited

429. More than 120 requests in a minute with the same key. Wait what Retry-After says.

translation-failed

422. No model gave a valid translation for some sentence; errors says which ones. Repeating the request gives the same result: remove or change them.

engine-unavailable

503. The translation engine is not answering. Try again shortly.

engine-mismatch

502. The engine answered something that does not match what was asked. Try again.

qe-unavailable

503. The scorer is not answering. Try again shortly, or translate with qe: false.

invalid-document

400. The document cannot be translated: its format is not one of the supported ones.

document-rejected

400 or 413. The file was rejected: it is empty (400) or larger than 50 MB (413).

job-not-found

404. There is no job with that id in your organisation.

job-not-ready

409. The job has no translated file: it has not finished, or it failed.

job-busy

409. The job is queued or running, and what you ask needs it to be over. Wait, or cancel it first.

segment-not-found

404. The document has no sentence at that position.

segment-locked

409. The sentence is locked and cannot be changed.

invalid-segment

400. The correction is not valid: usually, it does not carry the same formatting marks as the source.

invalid-resource

400. The memory or the glossary cannot be created: its file format, its name or its languages are wrong.

resource-not-found

404. There is no memory or glossary with that id in your organisation.

resource-busy

409. The memory or the glossary is still being indexed. Wait until its status is ready.

resource-language-mismatch

400. A memory or a glossary is for another language pair than the request.

entry-not-found

404. The memory or the glossary has no entry with that id.

invalid-entry

400. The entry is not valid: empty, or too long.

project-not-found

404. There is no project with that id in your organisation.

invalid-project

400. The name of the project is not valid.

request-not-found

404. There is no request with that id in your organisation.

not-found

404. The route does not exist.

storage-unavailable

503. A service behind the API is not answering. The same goes for store-unavailable and usage-unavailable. Try again shortly.

internal

500. Something went wrong on our side. Write to us with the X-Request-Id.

Limits

What	Limit
Requests per key	120 per minute
Sentences per POST /v1/translate	50
Characters per sentence	2,000
Characters per POST /v1/translate	10,000
Translations per POST /v1/qe	100
Memories or glossaries named in one request	20 of each
File size (documents, memories, glossaries)	50 MB
Period of one GET /v1/usage query	1 year