Guia

Tratamento de Erros

Toda requisição v1 com falha — toda resposta não-2xx — retorna a mesma estrutura JSON, listada abaixo na íntegra. Esta página também é o que o doc_url de cada erro referencia: cada código tem sua própria seção ancorada, então seguir um doc_url de uma resposta de erro real leva você diretamente à explicação daquele código exato.

A estrutura do erro

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_parameter",
    "message": "A required parameter is missing.",
    "doc_url": "https://imagetotable.ai/developers/guides/errors#missing_parameter",
    "param": "file"
  }
}
  • type — a categoria ampla na qual este erro se enquadra (veja a tabela abaixo). Útil para ramificações genéricas no seu código de tratamento de erros ("isto é um problema de autenticação ou de validação") sem verificar cada code individual.
  • code — o identificador de erro específico e estável. É nele que você deve basear suas comparações no código — ele não mudará mesmo se a redação do message for melhorada posteriormente.
  • message — uma explicação legível para humanos. Útil para logs e depuração, não deve ser interpretada programaticamente.
  • doc_url — um link direto para a seção desta página referente àquele code exato.
  • param — presente apenas em erros do tipo validação (missing_parameter, invalid_parameter, duplicate_field_name), nomeando o campo específico da requisição que causou o erro. Omitido completamente — não null — quando não aplicável.

Tipos de erro

Cada code pertence exatamente a um type:

TipoSignificado
authentication_errorAlgo está errado com a forma como você autenticou a requisição (ou se a autenticou).
invalid_request_errorA requisição em si está malformada — um parâmetro ausente ou inválido.
not_found_errorO recurso referenciado na URL (um ID de documento, lote ou modelo) não existe ou não pertence à sua conta.
insufficient_creditsSua conta não tem créditos suficientes para realizar a ação (paga) solicitada.
rate_limit_errorVocê excedeu a taxa de requisições para esta categoria de endpoint — consulte Limites de Taxa.
internal_errorAlgo deu errado em nosso lado, não no seu.

Um caso especial: processing_error

processing_error não é um type que você verá em uma resposta de nível superior {"error": ...}. Ele nunca faz com que uma chamada de API falhe por si só. Em vez disso, descreve um único documento dentro de um lote que não pôde ser extraído — você o verá refletido como "status": "failed" naquele documento dentro de uma resposta GET /batches/{batch_name}/results que, de outra forma, retorna 200 OK, junto com outros documentos no mesmo lote que foram processados com sucesso. Não trate uma falha no nível do documento dentro de uma chamada de API bem-sucedida como um erro para repetir o lote inteiro — verifique o status de cada documento individualmente.

Códigos de erro

missing_api_key

Tipo: authentication_error · Código HTTP: 401

Nenhuma chave de API foi fornecida. Envie-a como Authorization: Bearer <key>.

invalid_api_key

Tipo: authentication_error · Código HTTP: 401

A chave de API fornecida é inválida ou a conta à qual ela pertence está desativada.

plan_required

Tipo: authentication_error · Código HTTP: 403

A API não está disponível no plano Free. Faça upgrade para Basic ou superior para usá-la.

missing_parameter

Tipo: invalid_request_error · Código HTTP: 400

Um parâmetro obrigatório está faltando. Verifique param no objeto de erro para identificar qual.

invalid_parameter

Tipo: invalid_request_error · Código HTTP: 400

Um parâmetro tem um valor inválido. Verifique param e message para obter detalhes — este é um código genérico que cobre desde uma string crop malformada até um limit fora do intervalo ou um lote sem itens elegíveis para processamento.

duplicate_field_name

Tipo: invalid_request_error · Código HTTP: 400

Um campo com este nome já existe neste modelo. Os nomes dos campos devem ser únicos dentro de um modelo.

idempotency_key_reused

Tipo: invalid_request_error · Código HTTP: 400

Este Idempotency-Key já foi usado para uma solicitação com parâmetros diferentes. Use uma nova chave para uma solicitação genuinamente diferente — consulte Idempotência para o comportamento completo.

document_not_found

Tipo: not_found_error · Código HTTP: 404

Nenhum documento foi encontrado com o ID fornecido (ou ele não existe, ou não pertence à sua conta).

batch_not_found

Tipo: not_found_error · Código HTTP: 404

Nenhum lote foi encontrado com o nome fornecido.

template_not_found

Tipo: not_found_error · Código HTTP: 404

Nenhum modelo foi encontrado com o ID fornecido.

insufficient_credits

Tipo: insufficient_credits · Código HTTP: 402

Créditos insuficientes para realizar esta ação. Verifique GET /account para saber seus available_credits atuais antes de tentar novamente.

rate_limit_exceeded

Tipo: rate_limit_error · Código HTTP: 429

Muitas requisições. Reduza a velocidade e tente novamente após o período de reinicialização — consulte o cabeçalho de resposta X-RateLimit-Reset e o guia de Limites de Taxa.

internal_error

Tipo: internal_error · Código HTTP: 500

Ocorreu um erro inesperado. Se isso persistir, o problema é nosso, não seu — se você conseguir reproduzi-lo de forma confiável, essa é uma informação útil para incluir se você entrar em contato conosco.

📮 contact email: [email protected]