# Hark AI Translate > Translate with POST /text, /texts, /json, and /html across 249 languages. Short text median latency 146 ms on measured production traffic. HarkTranslate is a translation API. Send JSON with the x-hark-key header to https://edge.harktranslate.com/api/v1/translator. It accepts 249 language codes, and auto when the source should be detected. A successful translation is HTTP 200. ## Capabilities - Four formats: POST /text sends one string. POST /texts sends a list. POST /json translates string values and leaves keys and types in place. POST /html translates visible text and leaves tags in place. - Quality grades: A request may set quality. llm, nmt, and literal serve only that grade and answer 503 rather than a lower one. auto-latency, the default, returns the fastest answer of any grade. auto-llm prefers an LLM answer and returns a faster answer when the LLM one is late. - The grade in every response: Every translation carries meta: the quality you sent, the grade that served (literal, nmt, or llm), and degraded_segments, the protected parts that could not be restored. - Glossary: A glossary maps a source term to the target wording. Matching terms are masked before translation and restored as that target string, or left untouched if a placeholder would collide. - Protected words, paths, and selectors: do_not_translate and plan protected words pass through unchanged. JSON skips protected_paths and common_protected_paths. HTML skips nodes matched by protected_selectors. - Batch: POST /texts is one call for many strings. JSON and HTML documents are split into segment batches and written back into the original structure. ## Plans BASIC: 500 requests per month, hard cap, 8 KB, Standard queue, Email, 1,000 / hour. PRO: 48,000 requests per month, soft, +$0.0008 per extra request, 40 KB, Standard queue, Priority email, 50 / sec. ULTRA: 160,000 requests per month, soft, +$0.0006 per extra request, 80 KB, Priority queue, Dedicated, no published rate limit. MEGA: 480,000 requests per month, soft, +$0.0004 per extra request, 160 KB, Priority queue, Dedicated, no published rate limit. A body over the plan ceiling returns 413 and is not billed. Custom volume uses the contact form. Plan limits are published on the homepage FAQ: https://harktranslate.com/#faq ## Canonical pages - [Home](https://harktranslate.com/): Translate with POST /text, /texts, /json, and /html across 249 languages. Short text median latency 146 ms on measured production traffic. - [Quickstart](https://harktranslate.com/docs): Call the Hark translation API: one key, JSON in, translated text, JSON, or HTML out. Reference for every public endpoint. - [Swagger UI](https://harktranslate.com/docs/swagger): Interactive Swagger UI for the public translator spec. Authorize with the x-hark-key header. - [List languages](https://harktranslate.com/docs/support-languages): Returns every language code this API accepts, including auto. - [Translate text](https://harktranslate.com/docs/text): Translates one plain-text string. HTML is translated by POST /html. - [Translate many strings](https://harktranslate.com/docs/texts): Translates a list of plain-text strings in one request. Order and length are preserved. - [Translate JSON](https://harktranslate.com/docs/json): Translates string values inside a JSON value and returns the same structure. - [Translate HTML](https://harktranslate.com/docs/html): Translates visible text nodes and returns the markup with tags left in place. - [Detect language](https://harktranslate.com/docs/detect-language): Identifies the language of one string. This route does not translate and does not accept the translate options. - [Errors](https://harktranslate.com/docs/errors): Machine codes the Hark translation API returns, with HTTP status, meaning, and the change to make. Covers 200, 202, 400, 401, 403, 404, 413, 429, and 503. ## Endpoints ## GET /support-languages Returns every language code this API accepts, including auto. Docs: https://harktranslate.com/docs/support-languages Request fields: - This route has no request body. Response fields: - code (string): Language code to send as from or to. - language (string): English name of that code. ## POST /text Translates one plain-text string. HTML is translated by POST /html. Docs: https://harktranslate.com/docs/text Request fields: - from (required, string): Source language code. The value auto asks the service to detect the source. - to (required, string): Language code to translate into. - text (required, string): The string to translate, or the text whose language should be identified. - quality (optional, string): The grade of answer you accept. llm, nmt and literal serve only that grade and respond 503 when it cannot be served. auto-latency (the default) returns the fastest answer of any grade. auto-llm prefers an LLM answer and returns the fastest other answer when the LLM one is late. meta.grade reports what actually served. - context (optional, string): Optional content register. Omit it to use the default register. - glossary (optional, array of { source: string, target: string }): Replaces each source term with its target after translation. Omitted or empty leaves the text unchanged. - do_not_translate (optional, string[]): Terms copied through unchanged. Omitted or empty leaves the text unchanged. Response fields: - trans (string): Translated text, in the same order as the input when the input is a list. - source_language_code (string): Detected source language code. - source_language (string): Detected source language name. - trust_level (number): How confident detection was. - dict (object or null): Dictionary data when any was returned. - meta.quality (string): The quality the request sent, or auto-latency when it sent none. - meta.grade (string): Grade of the answer that was served: literal, nmt or llm. - meta.degraded_segments (number): How many protected parts of the answer could not be restored. ## POST /texts Translates a list of plain-text strings in one request. Order and length are preserved. Docs: https://harktranslate.com/docs/texts Request fields: - from (required, string): Source language code. The value auto asks the service to detect the source. - to (required, string): Language code to translate into. - texts (required, string[]): Plain-text strings translated in order. The response array has the same length and order. - quality (optional, string): The grade of answer you accept. llm, nmt and literal serve only that grade and respond 503 when it cannot be served. auto-latency (the default) returns the fastest answer of any grade. auto-llm prefers an LLM answer and returns the fastest other answer when the LLM one is late. meta.grade reports what actually served. - context (optional, string): Optional content register. Omit it to use the default register. - glossary (optional, array of { source: string, target: string }): Replaces each source term with its target after translation. Omitted or empty leaves the text unchanged. - do_not_translate (optional, string[]): Terms copied through unchanged. Omitted or empty leaves the text unchanged. Response fields: - trans (string[]): Translated text, in the same order as the input when the input is a list. - meta.quality (string): The quality the request sent, or auto-latency when it sent none. - meta.grade (string): Grade of the answer that was served: literal, nmt or llm. - meta.degraded_segments (number): How many protected parts of the answer could not be restored. ## POST /json Translates string values inside a JSON value and returns the same structure. Docs: https://harktranslate.com/docs/json Request fields: - from (required, string): Source language code. The value auto asks the service to detect the source. - to (required, string): Language code to translate into. - quality (optional, string): The grade of answer you accept. llm, nmt and literal serve only that grade and respond 503 when it cannot be served. auto-latency (the default) returns the fastest answer of any grade. auto-llm prefers an LLM answer and returns the fastest other answer when the LLM one is late. meta.grade reports what actually served. - context (optional, string): Optional content register. Omit it to use the default register. - protected_paths (optional, string[]): Dot paths whose values are not translated. - common_protected_paths (optional, string[]): Key names left untranslated at every nesting level. - json (required, object or JSON string): String values are translated. Keys, numbers, booleans, and null stay as sent. - glossary (optional, array of { source: string, target: string }): Replaces each source term with its target after translation. Omitted or empty leaves the text unchanged. - do_not_translate (optional, string[]): Terms copied through unchanged. Omitted or empty leaves the text unchanged. Response fields: - trans (object or array): Translated text, in the same order as the input when the input is a list. - meta.quality (string): The quality the request sent, or auto-latency when it sent none. - meta.grade (string): Grade of the answer that was served: literal, nmt or llm. - meta.degraded_segments (number): How many protected parts of the answer could not be restored. ## POST /html Translates visible text nodes and returns the markup with tags left in place. Docs: https://harktranslate.com/docs/html Request fields: - from (required, string): Source language code. The value auto asks the service to detect the source. - to (required, string): Language code to translate into. - quality (optional, string): The grade of answer you accept. llm, nmt and literal serve only that grade and respond 503 when it cannot be served. auto-latency (the default) returns the fastest answer of any grade. auto-llm prefers an LLM answer and returns the fastest other answer when the LLM one is late. meta.grade reports what actually served. - context (optional, string): Optional content register. Omit it to use the default register. - html (required, string): Text nodes are translated. Tags, attributes, and classes are returned unchanged. - glossary (optional, array of { source: string, target: string }): Replaces each source term with its target after translation. Omitted or empty leaves the text unchanged. - do_not_translate (optional, string[]): Terms copied through unchanged. Omitted or empty leaves the text unchanged. - protected_selectors (optional, string[]): Matching elements and their subtrees stay untranslated. Applies when the body is HTML. Response fields: - trans (string): Translated text, in the same order as the input when the input is a list. - meta.quality (string): The quality the request sent, or auto-latency when it sent none. - meta.grade (string): Grade of the answer that was served: literal, nmt or llm. - meta.degraded_segments (number): How many protected parts of the answer could not be restored. ## POST /detect-language Identifies the language of one string. This route does not translate and does not accept the translate options. Docs: https://harktranslate.com/docs/detect-language Request fields: - text (required, string): The string to translate, or the text whose language should be identified. Response fields: - trust_level (number): How confident detection was. - source_lang_code (string): Detected language code. - source_lang (string): Detected language name. ## Quality and response meta Every translate endpoint (/text, /texts, /json, /html) takes one routing field, quality: literal, nmt, llm, auto-llm, auto-latency. Omitted is auto-latency. - llm, nmt, literal: only that grade is served. When it cannot be served right now the answer is 503 with Retry-After: 30 (LLM_UNAVAILABLE for llm, QUALITY_UNAVAILABLE otherwise). - auto-llm: prefers an LLM answer and returns a faster answer when the LLM one is late. - auto-latency: the fastest answer of any grade. Every successful translate response carries meta: quality (as sent, or the default), grade (literal, nmt, or llm, what actually served), and degraded_segments (protected parts that could not be restored). The serving provider is not on the body. Migration: priority, on_llm_unavailable, mode, and engine were removed. A body that still sends one gets 400 naming the quality to send. priority quality becomes quality llm, priority latency and mode speed become quality auto-latency, on_llm_unavailable degrade becomes quality auto-llm, and engine has no replacement. ## Errors Docs: https://harktranslate.com/docs/errors - 400 Bad Request: The body failed validation: a missing field, a language code the endpoint does not accept, a quality outside its list (quality must be one of: literal, nmt, llm, auto-llm, auto-latency), a glossary or selector that breaks its rules, or json that does not parse. A body that still sends a removed field (priority, on_llm_unavailable, engine, or mode) is refused with a message naming the quality value to send instead. An unknown provider value is refused the same way, and the message lists the providers this API accepts. HTML sent to a plain-text route is refused and pointed at POST /html. Neither refusal spends quota. Fix: Change the field the message names. Send quality, not a removed field. Quota is not charged for this refusal. - 400 provider microsoft serves quality nmt only; send quality nmt, auto-llm or auto-latency, or omit provider: A provider that serves only nmt refuses quality llm and quality literal before quota is spent. The message tells you to send quality nmt, auto-llm, or auto-latency, or omit provider. Fix: Send quality nmt, auto-llm, or auto-latency, or omit provider. - 400 X-RapidAPI-User is required before a translation job can be accepted. This request was not queued. Send the header and retry.: RapidAPI refuses to queue a job when the end-user header is missing. This is the JOB_USER_REQUIRED message. Fix: Send X-RapidAPI-User and retry. The request was not queued. - 400 PROXY_RETRY_EXHAUSTED: The service used its retries and still had no answer. Fix: Retry later. If it continues, include requestId when you report it. - 400 UPSTREAM_TIMEOUT: The translator did not answer before its deadline. Fix: Retry later. If it continues, include requestId when you report it. - 400 UPSTREAM_HTTP_ERROR: The translator answered with an error status instead of a translation. Fix: Retry later. If it continues, include requestId when you report it. - 400 UPSTREAM_RATE_LIMITED: The translator refused the call because it was rate-limited. Fix: Retry later. If it continues, include requestId when you report it. - 400 UPSTREAM_INCOMPLETE_TRANSLATION: The translator answered without a complete translation, so nothing was returned in its place. Fix: Retry later. If it continues, include requestId when you report it. - 400 ENGINE_UNAVAILABLE: The translator this request needed was not available. Fix: Retry later. If it continues, include requestId when you report it. - 400 ENGINE_CASCADE_EXHAUSTED: Every translator this request could use failed on it. Fix: Retry later. If it continues, include requestId when you report it. - 400 REQUEST_DEADLINE_EXCEEDED: The request ran past its deadline. Fix: Retry later. If it continues, include requestId when you report it. - 400 RETRY_BUDGET_EXHAUSTED: The request used every retry its budget allows. Fix: Retry later. If it continues, include requestId when you report it. - 400 ENGINE_CALL_CEILING_REACHED: This document used the call allowance for one request. Fix: Split the document into smaller requests, then retry. - 400 INTERNAL_UNKNOWN: The failure was not classified. The public message stays the fixed system sentence. Fix: Retry later. If it continues, include requestId when you report it. - 400 GRADE_UNAVAILABLE: The requested grade could not be served, and a lower grade was not substituted. Fix: Retry later, or send another quality. - 400 DETECT_PROBE_EMPTY: Language detection is fail-closed on an empty probe. After trim, the text had no characters, so no language is guessed. Fix: Send text that still has characters after trimming. - 400 DETECT_SOURCE_MISSING: Language detection is fail-closed when the probe does not name a language this API publishes. No guessed code is returned. Fix: Retry with a longer sentence. If it still fails, set from to a language code instead of auto. - 401 Missing API key: No customer key was sent. Send x-hark-key on every request. The legacy header x-aibit-key is still accepted. Samples use x-hark-key. Fix: Add the x-hark-key header. A missing key does not spend quota. - 401 Invalid API key: The key is not a known key, or it is not attached to an account. Fix: Send a current key in x-hark-key. - 403 API key revoked: The key was revoked. Fix: Issue a new key and send it in x-hark-key. - 403 Tenant suspended: The account is suspended. Fix: Use a key on an active account. - 403 Provider not allowed: The message is Provider '' is not allowed for plan ''. The plan does not allow that provider. Fix: Omit provider, or send a provider the plan allows. - 403 Context 'adult' is not served on Microsoft lanes: The explicit register is refused before quota is spent when that provider lane does not serve it. Fix: Omit context, or call a lane that serves the register. - 403 plan does not include the engine this request needs: The message is plan '' does not include the engine this request needs. Detection uses the same refusal when the plan excludes every translator it can run. Fix: Use a plan that includes this request, or change quality. - 403 This endpoint only accepts requests from an authorized RapidAPI listing: The RapidAPI channel rejected the proxy secret or the listing host. One message covers every cause. Fix: Call through the listing that issued the key. Direct calls use a customer key, not the RapidAPI proxy secret. - 404 Not Found: The path is not one of the translator endpoints. The service answers an unknown route with 404. Fix: Use a path from the API reference. - 404 Translation job not found: A RapidAPI job poll uses this JOB_NOT_FOUND message when the caller cannot read that id, including a poll with no end-user header. Fix: Poll the job id from the submit response with the same X-RapidAPI-User. - 413 Payload Too Large: A direct x-hark-key request whose body is over 50 MB gets 413 with no plan, max_bytes, or received_bytes fields. On the RapidAPI channel, 413 means the body is over that plan ceiling, and the response names plan, max_bytes, and received_bytes. Fix: Send a smaller body. On RapidAPI, read max_bytes and stay under it. - 429 Rate limit exceeded: The plan rate limit was exceeded. This refusal does not consume monthly quota. Fix: Wait and retry. - 429 Monthly quota exceeded: The monthly quota is spent and overage is off. A quota refusal still returns the allowance headers. Fix: Wait until the quota resets, or enable overage on the account. - 429 Too many translation jobs are waiting; retry shortly: Only the RapidAPI channel returns this 429, when it cannot accept another queued job. Fix: Retry shortly, or send a smaller job. - 503 LLM_UNAVAILABLE: quality llm answers LLM_UNAVAILABLE when no llm translation is available. The same code is used when a protected segment could not be restored. Both carry Retry-After: 30. A strict quality never falls back to another grade. Fix: Retry after the Retry-After delay, or send another quality. - 503 QUALITY_UNAVAILABLE: Every quality other than llm answers QUALITY_UNAVAILABLE when that grade cannot be served. The response carries Retry-After: 30. A strict quality (nmt, literal) never falls back to another grade. Fix: Retry after the Retry-After delay, or send another quality. - 503 no engine for adult-context requests is available right now; retry later: When context asks for the explicit register and nothing that can serve it is on, the API returns 503 with this message. The request is not served on another register. Fix: Retry later, or omit context to use the default register. - 202 ASYNC_PAYLOAD_TOO_LARGE: RapidAPI answered 202 and marked the job failed because the payload cannot finish inside the async cap. The job body carries this code. This is not a successful accept. Fix: Split the payload, or shorten the text so it can finish inside the plan cap. - 200 JOB_TIMEOUT: A RapidAPI job poll returns HTTP 200 with job status timeout and this code when the job exceeded its cap. The message states the cap it ran past. HTTP 200 here is the poll, not a successful translation. Fix: Split the payload into smaller jobs and submit again. - 200 HTTP_: A RapidAPI job that failed on an HTTP exception records error.code as HTTP_. Callers see HTTP_400, HTTP_413, HTTP_429, and HTTP_503. The poll itself stays HTTP 200. Fix: Read error.code and error.message on the job, then correct the request or retry a 429 or 503.