Códigos de erro da API

Referência completa de cada código de erro que a API pode retornar, com o status HTTP, quando ocorre e como se recuperar.

Envelope de erro

Cada resposta de erro usa a mesma estrutura JSON canônica:

JSON
{
  "error": {
    "code": "FILE_TOO_LARGE",
    "message": "File is too large. Maximum size is 200 MB.",
    "details": { "max_bytes": 209715200, "received_bytes": 240000000 }
  }
}

Sempre verifique também o status code HTTP — ele fornece a categoria geral (4xx = erro do cliente, 5xx = erro do servidor).

Referência de códigos de erro

CódigoHTTPQuandoComo recuperar
NO_FILE 400 Você esqueceu de anexar um campo file, ou o upload multipart estava malformado. Envie a requisição como multipart/form-data com um campo file. Para endpoints batch, use files[].
INVALID_FORMAT 400 Você esqueceu to_format, ou a conversão solicitada não é suportada (por ex. jpg → zzz). Passe um to_format válido. Veja a referência do convert para a lista completa de formatos suportados.
FILE_TOO_LARGE 413 O arquivo enviado excede o limite de tamanho (200 MB padrão, menor para algumas ferramentas de IA). Redimensione/comprima o arquivo antes do upload, ou divida-o em pedaços menores.
UNSUPPORTED_MIME 415 O tipo MIME do arquivo não está na nossa whitelist (por ex. .exe, .zip quando não esperado). Confirme o formato do seu arquivo. Verifique os formatos suportados na página inicial.
RATE_LIMITED 429 Você atingiu um dos 5 níveis de rate limit. Respeite o cabeçalho Retry-After. Veja os limites de taxa.
JOB_NOT_FOUND 404 O job_id não existe (erro de digitação, nunca criado), ou expirou (jobs são mantidos por 2 horas). Verifique se o job_id tem exatamente 32 caracteres hexadecimais e foi criado nas últimas 2 horas.
JOB_EXPIRED 410 O job tem mais de 2 horas e o arquivo convertido foi excluído automaticamente. Reenvie a conversão. Sempre baixe o resultado prontamente após a conclusão do job.
CONVERSION_FAILED 500 O mecanismo de conversão foi executado, mas falhou (por ex. origem corrompida, dependências ausentes, exceção interna). Verifique error.message para os detalhes. Tente outro arquivo. Relate falhas repetidas via /contact.
BATCH_TOO_LARGE 400 Sua requisição POST /api/v1/batch tinha mais de 20 arquivos. Divida seu batch em lotes de ≤20 arquivos.
NOT_FOUND 404 Endpoint desconhecido ou slug de ferramenta desconhecido (por ex. /api/v1/tools/foobar). Verifique a ortografia. Consulte /api/reference para endpoints válidos.
NOT_IMPLEMENTED 501 O endpoint existe na nossa documentação, mas ainda não está conectado no servidor (por ex. flip-image). Use uma solução alternativa (por ex. /api/v1/convert com img_rotate=flip-h) ou aguarde o lançamento do recurso.
BANNED 403 Seu IP gerou mais de 10 recusas de rate limit em 1 hora e agora está banido por 24 horas. Aguarde o banimento expirar (veja Retry-After). Se for IP compartilhado, contate-nos via /contact.
INTERNAL_ERROR 500 Falha inesperada no servidor. Deveria ser raro. Tente novamente uma vez após alguns segundos. Se persistir, relate via /contact com o cabeçalho X-Request-Id da resposta.

O cabeçalho X-Request-Id

Toda resposta da API (sucesso ou erro) inclui um cabeçalho X-Request-Id. Ao relatar um problema, inclua este ID para que possamos encontrar a requisição em nossos logs:

HTTP headers
X-Request-Id: 4f2dc3b5cc79fa57

Solicitar um recurso

0 / 2000