Saltar para o conteúdo principal
idempotencyKey é uma string opcional que você define em um envio. Envie a mesma chave de novo e você recebe a tarefa que o primeiro envio criou; nenhum trabalho novo entra na fila e nenhuma nova reserva de créditos é feita.
Sem chave não há deduplicação: cada envio cria uma nova tarefa. Defina uma chave em tudo que um cron job ou um worker com novas tentativas possa enviar duas vezes.
Monte a chave a partir da unidade de trabalho, não da tentativa. Uma chave como "{jobId}:{promptId}:{engine}" sai igual em toda nova tentativa desse trabalho.

Como cada endpoint trata uma chave repetida

O endpoint de tarefa individual mantém a semântica de criação explícita: você pediu para criar uma tarefa que já existe, então recebe um conflito. O erro traz o id da tarefa existente em error.details.taskId, então um envio sem resposta pode ser recuperado consultando esse id.
O lote de 500 tarefas absorve duplicatas como sucesso, então um worker pode reenviar um job inteiro depois de reiniciar sem que o lote falhe nos itens que já tinham entrado.

Grades de localização

O idempotencyKey da grade vira o id dela (um UUID é gerado quando você o omite). A chave da tarefa de cada ponto é <grid id>:r<row>c<col>. Enviar a mesma grade de novo com esse id devolve os pontos existentes e admite só os que faltam. Enviar com o mesmo id uma grade com outro centro, tamanho ou raio faz falhar com RESOURCE_ALREADY_EXISTS os pontos cujas coordenadas diferem; use uma chave nova para uma grade nova.

Escopo e tamanho

As chaves têm escopo na sua conta: outra conta pode usar a mesma string sem colidir com a sua. O formato UUID não é obrigatório.

Relacione resultados aos envios

Se você não enviou chave, idempotencyKey é omitido do objeto da tarefa, e não devolvido como null.

Vida útil da chave

Uma chave continua reservada por pelo menos 30 dias depois da solicitação, inclusive depois que a tarefa é concluída ou falha e depois que a janela de polling de 24 horas fecha. Um 404 no polling não libera a chave. Use a mesma chave nas novas tentativas de transporte de um envio, e uma chave nova (por exemplo, com o sufixo :r1) para uma execução separada do mesmo trabalho.

Próximos passos

Lotes e grades

Os três endpoints de envio em massa lado a lado.

Erros

Todos os códigos de erro de requisição.