Erros

Todas as falhas da API usam o mesmo envelope. Faça o direcionamento lógico com base em error.code, nunca na mensagem legível por humanos.

{
  "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

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

authentication_required

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

invalid_api_key

A chave está malformada ou é desconhecida. Verifique se todo o valor aig_live_… foi copiado.

api_key_expired

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

api_key_revoked

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

insufficient_scope

A credencial foi autenticada, mas não possui o escopo necessário para esta operação.

feature_not_available

O plano do workspace ou a versão atual da plataforma não inclui o recurso solicitado.

admin_required

Apenas administradores do workspace podem realizar esta operação.

Códigos de requisição

invalid_request

A requisição não pôde ser analisada ou não corresponde ao contrato do endpoint.

unknown_field

Uma propriedade do corpo JSON não foi reconhecida. Corrija a grafia em vez de remover a validação. Parâmetros de consulta (query) não reconhecidos nunca geram este erro; eles são ignorados, portanto, um filtro digitado incorretamente retornará um 200 sem filtros.

invalid_parameter

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

invalid_cursor

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

request_too_large

O corpo da requisição excede o limite rígido do endpoint.

Códigos de recurso e estado

batch_not_found

Nenhuma tradução visível possui esse ID. Recursos em outro workspace retornam intencionalmente o mesmo erro.

glossary_not_found

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

resource_not_found

O recurso ou rota solicitada não existe.

glossary_already_exists

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

result_not_ready

A tradução ainda não foi concluída, portanto nenhum resultado pode ser baixado no momento.

batch_not_editable

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

Códigos de arquivo e formato

unsupported_format

A extensão do arquivo não é aceita pelo AI Glot. Consulte Arquivos e formatos para conhecer as doze famílias e suas respectivas extensões.

file_too_large

O arquivo excede o limite máximo permitido para o seu formato. Os limites são definidos por formato e não globalmente (60 MB para CSV, 4 MB para catálogo PO), de modo que um tamanho aceito para uma extensão pode ser recusado para outra.

file_fetch_failed

Não foi possível obter a file_url. A URL precisa ser HTTPS e deve ser o destino final: redirecionamentos não são seguidos, portanto links encurtados ou assinados com redirecionamento falharão aqui.

file_retention_expired

O arquivo enviado ultrapassou a janela de retenção e não está mais armazenado. Crie a tradução novamente a partir do arquivo de origem.

file_expired

O arquivo que dá suporte a esta tradução não existe mais, portanto a operação não pode prosseguir.

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

A instrução ou o refinamento não pôde ser convertido em um plano utilizável. Reformule-a: especificar os nomes dos campos ou colunas a serem traduzidos é mais confiável do que descrevê-los.

no_plan_yet

A aprovação foi solicitada antes da existência de um plano. Chame POST /v1/batches/{batch_id}/plan primeiro; essa proteção impede que uma integração cobre um workspace por uma tradução que ninguém definiu.

batch_not_awaiting_approval

A tradução não está em um estado passível de aprovação; geralmente, ela já está em execução ou foi concluída. Faça polling em GET /v1/batches/{batch_id} em vez de aprovar novamente.

insufficient_credits

O saldo do workspace não é suficiente para cobrir o custo calculado do plano. Nada é reservado, portanto a tradução continua disponível para aprovação assim que novos créditos forem adicionados.

Códigos de idioma e glossário

language_not_supported

A tag informada não faz parte do catálogo suportado. Consulte GET /v1/languages.

invalid_language_pair

O identificador do par de idiomas não pôde ser dividido em duas tags BCP 47 suportadas.

glossary_term_limit_reached

A quantidade resultante de termos excederia o limite do plano do workspace. A atualização é atômica; nenhuma alteração foi aplicada.

glossary_limit_reached

O workspace atingiu o limite de glossários permitido para o plano atual.

invalid_glossary_terms

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

Códigos de serviço

rate_limited

A credencial excedeu a janela de taxa de requisições. Aguarde o tempo indicado em Retry-After e tente novamente com variação aleatória (jitter).

internal_error

O AI Glot apresentou uma falha inesperada. Tente novamente com backoff e guarde o request_id.

service_unavailable

Um serviço obrigatório está temporariamente indisponível. Tente novamente com backoff.