Send x-hark-key on every request. The legacy header x-aibit-key is still accepted. Samples use x-hark-key.
A system failure is HTTP 400. message is "Something went wrong please try again later". errorCode is one of the codes under 400, and requestId is included. The same errorCode can appear on HTTP 503 when the message says the translator failed and was not substituted.
400 Bad Request
Bad Request- Explanation
- 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.
provider microsoft serves quality nmt only; send quality nmt, auto-llm or auto-latency, or omit provider- Explanation
- 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.
X-RapidAPI-User is required before a translation job can be accepted. This request was not queued. Send the header and retry.- Explanation
- 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.
PROXY_RETRY_EXHAUSTED- Explanation
- The service used its retries and still had no answer.
- Fix
- Retry later. If it continues, include requestId when you report it.
UPSTREAM_TIMEOUT- Explanation
- The translator did not answer before its deadline.
- Fix
- Retry later. If it continues, include requestId when you report it.
UPSTREAM_HTTP_ERROR- Explanation
- The translator answered with an error status instead of a translation.
- Fix
- Retry later. If it continues, include requestId when you report it.
UPSTREAM_RATE_LIMITED- Explanation
- The translator refused the call because it was rate-limited.
- Fix
- Retry later. If it continues, include requestId when you report it.
UPSTREAM_INCOMPLETE_TRANSLATION- Explanation
- 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.
ENGINE_CASCADE_EXHAUSTED- Explanation
- Every translator this request could use failed on it.
- Fix
- Retry later. If it continues, include requestId when you report it.
REQUEST_DEADLINE_EXCEEDED- Explanation
- The request ran past its deadline.
- Fix
- Retry later. If it continues, include requestId when you report it.
RETRY_BUDGET_EXHAUSTED- Explanation
- The request used every retry its budget allows.
- Fix
- Retry later. If it continues, include requestId when you report it.
ENGINE_CALL_CEILING_REACHED- Explanation
- This document used the call allowance for one request.
- Fix
- Split the document into smaller requests, then retry.
INTERNAL_UNKNOWN- Explanation
- 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.
DETECT_PROBE_EMPTY- Explanation
- 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.
DETECT_SOURCE_MISSING- Explanation
- 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 Unauthorized
Missing API key- Explanation
- 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.
Invalid API key- Explanation
- 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 Forbidden
API key revoked- Explanation
- The key was revoked.
- Fix
- Issue a new key and send it in x-hark-key.
Tenant suspended- Explanation
- The account is suspended.
- Fix
- Use a key on an active account.
Provider not allowed- Explanation
- The message is Provider '<name>' is not allowed for plan '<plan>'. The plan does not allow that provider.
- Fix
- Omit provider, or send a provider the plan allows.
Context 'adult' is not served on Microsoft lanes- Explanation
- 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.
plan does not include the engine this request needs- Explanation
- The message is plan '<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.
404 Not Found
Not Found- Explanation
- 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.
Translation job not found- Explanation
- 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
Payload Too Large- Explanation
- 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 Too Many Requests
Rate limit exceeded- Explanation
- The plan rate limit was exceeded. This refusal does not consume monthly quota.
- Fix
- Wait and retry.
Monthly quota exceeded- Explanation
- 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.
Too many translation jobs are waiting; retry shortly- Explanation
- Only the RapidAPI channel returns this 429, when it cannot accept another queued job.
- Fix
- Retry shortly, or send a smaller job.
503 Service Unavailable
no engine for adult-context requests is available right now; retry later- Explanation
- 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 Accepted (failed job)
ASYNC_PAYLOAD_TOO_LARGE- Explanation
- 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 poll
JOB_TIMEOUT- Explanation
- 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.
HTTP_<status>- Explanation
- A RapidAPI job that failed on an HTTP exception records error.code as HTTP_<status>. 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.