Skip to content

Error catalog

Every code a caller can receive from the translator API, with the status, the meaning, and the change to make.

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_UNAVAILABLE

    Explanation
    The translator this request needed was not available.
    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.
  • GRADE_UNAVAILABLE

    Explanation
    The requested grade could not be served, and a lower grade was not substituted.
    Fix
    Retry later, or send another quality.
  • 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.
  • This endpoint only accepts requests from an authorized RapidAPI listing

    Explanation
    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

  • 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

  • LLM_UNAVAILABLE

    Explanation
    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.
  • QUALITY_UNAVAILABLE

    Explanation
    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.
  • 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.