AI Glot websiteOpen AI Glot
REST APIErros

Erros

Saiba como lidar com falhas da API do AI Glot usando códigos de erro estáveis, IDs de solicitação, orientações sobre novas tentativas e explicações com âncoras para cada erro documentado.

Todas as falhas da API usam o mesmo envelope. Use error.code para determinar como agir, nunca a mensagem legível por humanos.

Exemplo de erro
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This credential is missing the batches:write scope.",
    "docs_url": "https://ai-glot.com/docs/api/errors#insufficient_scope"
  },
  "request_id": "req_example"
}

Códigos de status

StatusSignificadoO que fazer
400Solicitação malformada ou campo desconhecidoCorrija a solicitação
401Credencial ausente, inválida, expirada ou revogadaSubstitua ou renove a credencial
403Autenticado, mas sem permissãoConceda o escopo ou recurso necessário
404Recurso inexistente ou fora deste espaço de trabalhoConfira o ID e o espaço de trabalho
409O estado atual é incompatível com a solicitaçãoConsulte o recurso e decida o que fazer
413Corpo da solicitação grande demaisEnvie um corpo menor
422Valor bem formado, mas inválidoCorrija o valor indicado
429Limite de requisições excedidoAguarde Retry-After
500/503O AI Glot falhou ou está temporariamente indisponívelTente novamente com espera progressiva

Códigos de autenticação e permissões

authentication_required

Nenhuma credencial bearer foi enviada. Adicione o cabeçalho Authorization.

invalid_api_key

A chave está malformada ou não é reconhecida. Confira se o valor aig_live_… completo foi copiado.

api_key_expired

A chave atingiu a data de expiração configurada. Crie ou use uma chave substituta.

api_key_revoked

Um administrador revogou ou substituiu esta chave. Atualize a integração com uma credencial ativa.

insufficient_scope

A credencial autenticou, mas não tem o escopo exigido por esta operação.

feature_not_available

O plano do espaço de trabalho ou a versão atual da plataforma não inclui o recurso solicitado.

admin_required

Somente um administrador do espaço de trabalho pode realizar esta operação.

Códigos de solicitação

invalid_request

Não foi possível interpretar a solicitação ou ela não corresponde ao contrato do endpoint.

unknown_field

Uma propriedade do corpo JSON não é reconhecida. Corrija a grafia em vez de desativar a validação. Parâmetros de consulta desconhecidos não geram este erro: eles são ignorados. Portanto, um filtro com erro de digitação retorna um 200 sem filtro.

invalid_parameter

Um parâmetro tem tipo, intervalo ou formato incorreto.

invalid_cursor

O cursor de paginação é inválido. Reutilize next_cursor exatamente como foi retornado.

request_too_large

O corpo da solicitação excede o limite máximo do endpoint.

Códigos de recursos e estado

batch_not_found

Nenhuma tradução visível tem esse ID. Os recursos de outro espaço de trabalho retornam intencionalmente o mesmo erro.

glossary_not_found

Não há glossário para esse par de idiomas.

resource_not_found

O recurso ou a rota solicitada não existe.

glossary_already_exists

Já existe um glossário para esse par de idiomas. Atualize-o em vez de criar outro.

result_not_ready

A tradução ainda não foi concluída, então não é possível baixar o resultado.

batch_not_editable

O estado atual da tradução não permite a alteração de manutenção solicitada.

idempotency_key_reused

A Idempotency-Key já foi usada para outro pedido (outro arquivo, nome ou instrução). Envie o mesmo pedido para repeti-lo, ou uma nova chave para um novo trabalho. Veja Criar uma tradução.

Códigos de arquivo e formato

unsupported_format

A extensão do arquivo não é aceita pelo AI Glot. Consulte Arquivos e formatos para ver todos os formatos e suas extensões.

file_too_large

O arquivo excede o limite para o formato correspondente. Os limites variam conforme o formato, não são globais (60 MB para CSV e 4 MB para um catálogo PO). Por isso, um tamanho aceito para uma extensão pode ser recusado para outra.

file_fetch_failed

Não foi possível obter file_url. A URL precisa usar HTTPS e apontar para o destino final: redirecionamentos não são seguidos, então um link encurtado ou que redirecione após ser assinado falhará aqui.

file_retention_expired

O período de retenção do arquivo enviado terminou e ele não está mais armazenado. Crie a tradução novamente usando o arquivo de origem.

file_expired

O arquivo associado a esta tradução não está mais disponível, então não é possível prosseguir com a operação.

result_too_large

A tradução concluída excede o tamanho máximo que pode ser retornado. Divida o arquivo de origem e traduza-o em partes.

Códigos de plano e aprovação

plan_invalid

Não foi possível transformar a instrução ou o refinamento em um plano utilizável. Nenhuma cobrança foi feita. Quando a causa é conhecida, a mensagem informa o motivo: nada no arquivo correspondia à instrução, a instrução pede para escrever em um local que o arquivo não comporta ou não foi possível gerar o plano desta vez (envie a mesma instrução novamente). Caso contrário, reformule-a: indicar os campos ou as colunas a traduzir é mais confiável do que descrevê-los.

plan_changed

O expected_plan_revision enviado não corresponde ao plano atual disponível para revisão, ou não foi possível verificar essa revisão. Esta aprovação não iniciou um novo trabalho. Leia o lote novamente, confira o escopo atual, as exclusões e o custo calculado e decida se deseja aprovar usando a nova revisão. Não tente aprovar novamente, sem conferir, com a revisão antiga.

no_plan_yet

A aprovação foi solicitada antes da criação de um plano. Primeiro, chame POST /v1/batches/{batch_id}/plan. Essa verificação impede que uma integração cobre do espaço de trabalho por uma tradução que ninguém especificou.

batch_not_awaiting_approval

A tradução não está em um estado que permita aprovação; geralmente, ela já está em andamento ou foi concluída. Consulte GET /v1/batches/{batch_id} em vez de aprovar novamente.

insufficient_credits

O saldo do espaço de trabalho não cobre o custo calculado do plano (HTTP 402). Nenhum crédito foi reservado, então será possível aprovar a tradução quando forem adicionados créditos.

O erro inclui um objeto payment, tanto na API REST quanto na ferramenta MCP approve_translation:

JSON
"payment": {
  "credits_needed": 30000,
  "credit_balance": 5000,
  "credits_missing": 25000,
  "credits_to_buy": 25000,
  "price_eur": 25,
  "payment_url": "https://app.ai-glot.com/w/<workspace_id>/new?continue=<batch_id>&pay=1",
  "plans": [
    { "plan": "Starter", "eur_per_month": 42, "credits_per_month": 100000 },
    { "plan": "Pro", "eur_per_month": 199, "credits_per_month": 1000000 }
  ]
}

credits_to_buy é a menor compra que cobre a diferença (aplica-se o valor mínimo de compra). payment_url abre esta tradução no AI Glot com a janela de compra já aberta: com o valor exato, os pacotes de créditos, os planos e a amostra grátis, caso o espaço de trabalho seja elegível. O link só funciona para um membro conectado ao espaço de trabalho, portanto, é seguro compartilhá-lo. plans lista os planos mensais, que oferecem um custo por crédito menor para quem traduz regularmente; eles também aparecem na mesma página, abaixo da opção de compra única.

Um agente deve perguntar ao usuário antes de oferecer o link, nunca pagar em nome dele e, após o pagamento, conferir o saldo com GET /v1/account e aprovar novamente quando o usuário confirmar. O usuário também pode iniciar a tradução nessa página.

Códigos de idioma e glossário

language_not_supported

A etiqueta não faz parte do catálogo de idiomas aceitos. Consulte GET /v1/languages.

invalid_language_pair

Não é possível dividir o identificador do par de idiomas em duas etiquetas BCP 47 aceitas.

glossary_term_limit_reached

A quantidade de termos resultante ultrapassaria o limite do plano do espaço de trabalho. A atualização é atômica; nada foi alterado.

glossary_limit_reached

O espaço de trabalho atingiu o número máximo de glossários permitido pelo plano atual.

invalid_glossary_terms

Uma ou mais entradas do glossário estão vazias, incompletas ou são inválidas por outro motivo.

Códigos de serviço

rate_limited

A credencial excedeu o limite de uma janela de requisições. Aguarde Retry-After e tente novamente com um atraso aleatório.

internal_error

O AI Glot falhou inesperadamente. Tente novamente com espera progressiva e mantenha o request_id.

service_unavailable

Um serviço necessário está temporariamente indisponível. Tente novamente com espera progressiva.

Use these docs with your AI tools

An AI agent can read this documentation directly. You do not need an account or an API key. Everything here is public and read-only.

Query these docs via MCP

Recommended

Add this server to Claude, Claude Code, Cursor, Mistral, or any tool that supports MCP. Your agent can then search AI Glot Docs documentation and read it in full, instead of answering from memory.

https://ai-glot.com/docs/mcp
  • searchFind the passages that answer a question.
  • fetchRead one page in full, as Markdown.
  • list_pagesSee every page in this documentation.

Query these docs over HTTP

The same tools also work as plain web requests. Use this for scripts, or for any tool that does not support MCP. There is one endpoint per tool. Arguments go in the query string, and the answer comes back as JSON.

https://ai-glot.com/docs/api/docs/search?query=custom+domain

Read the OpenAPI description. It is built from the same definitions as the tools, so it always matches what the endpoints do.

Read these docs as Markdown

Add .md to any page URL to get its Markdown source. You can also send the headerAccept: text/markdown to the page URL itself.

To read the whole documentation in one file, open llms-full.txt. For a short index of every page, open llms.txt.