⌘ KErros e limites
Trate falhas por arquivo e repita um envio somente com a mesma chave de idempotência e os mesmos bytes.
Nesta página
Respostas da API
| HTTP / código | Como tratar |
|---|---|
| 401 · API_KEY_INVALID | Confira chave, validade e revogação no painel. |
| 403 · API_PERMISSION / API_SERVER_ONLY | Use a chave no servidor e autorize Executar e Consultar. |
| 404 · NOT_FOUND | Confira o ID e a autorização dessa automação ou execução. |
| 409 · AUTOMATION_CONFLICT / AUTOMATION_PAUSED | Revise a versão ou o estado publicado no painel. |
| 409 · IDEMPOTENCY_CONFLICT | Use exatamente os mesmos arquivos e parâmetros no reenvio. |
| 409 · RESULT_UNAVAILABLE | Aguarde a conclusão antes de receber o arquivo. |
| 410 · EXPIRED | O resultado temporário expirou; não há cópia na biblioteca. |
| 413 · API_UPLOAD_LIMIT / FILE_TOO_LARGE | Reduza tamanho ou quantidade e respeite os limites técnicos e do plano. |
| 415 · MULTIPART_REQUIRED | Envie version e files como multipart/form-data. |
| 422 · INVALID_REQUEST / AUTOMATION_INVALID | Confira tipo dos arquivos, versão e configuração do gatilho no painel. |
| 429 · ACTIVE_JOB_LIMIT / USAGE_LIMIT / RATE_LIMITED | Aguarde o prazo informado; não troque de chave para contornar limites. |
| 503 · API_UPLOAD_BUSY / AUTOMATION_API_UNAVAILABLE | Aguarde e repita o mesmo envio lógico, preservando a chave. |
Recuperar um envio com segurança
POST /automations/:id/runs exige Idempotency-Key. Guarde-a antes de enviar. Uma repetição com os mesmos arquivos, nomes, ordem, versão e chave recupera a mesma execução, sem novo processamento ou cobrança duplicada.
Mudar bytes, nomes ou ordem com a mesma chave gera conflito. As consultas e o recebimento de resultados usam GET e não criam outra execução. Um ID recebido permite continuar acompanhando mesmo após o prazo local do cliente.
Limites de envio e processamento
| Limite | Regra |
|---|---|
| Por requisição | Até 80 MB incluindo o formulário. Os exemplos deixam margem para os campos. |
| Por arquivo | JPG, PNG, WebP ou AVIF estático; até 25 MB e limites de pixels do processamento. |
| Por lote | Sujeito aos limites técnicos, do plano e do gatilho publicado; não basta mudar a quantidade no código. |
| Concorrência | Cota de lotes ativos compartilhada com a conta; envios diretos também têm capacidade limitada. |
| Resultados | Disponíveis temporariamente por até 15 minutos após a conclusão. |
| Requisições | 120/min por integração; criação de execuções sujeita a limites adicionais. |
Créditos e armazenamento
As transformações confirmadas seguem as regras de uso e créditos da conta. Não se cobra sucesso por um arquivo que falhou ou foi cancelado. As cotas de processamento continuam autoritativas no backend.
A execução externa não consome a cota da biblioteca e não cria arquivos ou pastas no painel de armazenamento. O limite temporário de infraestrutura continua necessário para receber e processar o lote.
Falhas parciais
Avalie files[] e result por item. Um lote PARTIAL pode entregar resultados úteis; preserve esses arquivos no seu sistema e trate os demais pelo errorCode. Não repita automaticamente o lote inteiro como nova execução.