Envelope de erro
{
"error": {
"code": "asset_not_found",
"message": "No asset with id 42 for this shop",
"status": 404,
"request_id": "req_..."
}
}Inclua o request id ao entrar em contato com o suporte.
Códigos de erro comuns
| HTTP | Código | Significado |
|---|---|---|
| 400 | invalid_request | JSON malformado ou campo ausente. |
| 400 | idempotency_key_required | Requisição de escrita sem Idempotency-Key. |
| 401 | unauthorized | Token ausente, inválido, desconhecido ou revogado. |
| 402 | plan_required | A loja está no plano Free. A API externa exige um plano pago. Em uma notificação de atualização de produto, também significa que a assinatura da loja não está ativa, e uma campanha interrompida por qualquer um dos dois motivos depois de entrar na fila informa error: plan_required em GET /notifications/{id}. |
| 403 | forbidden | A API externa está desativada (o interruptor global de emergência), falta à chave de API um escopo de que a requisição precisa ou, nas rotas de notificações de atualização de produto, o Alva desativou essas notificações como freio de emergência. Entre em contato conosco se uma chave com os escopos corretos receber essa resposta. |
| 403 | notifications_suspended | As notificações de atualização de produto estão suspensas para esta loja após reclamações de spam em campanhas anteriores. Nenhuma nova tentativa ajuda — entre em contato com o suporte. |
| 404 | asset_not_found, mapping_not_found, order_not_found, category_not_found, job_not_found | O recurso não existe ou pertence a outra loja. |
| 404 | notification_not_found | A notificação de atualização de produto não existe ou pertence a outra loja. |
| 409 | idempotency_conflict | A mesma chave foi reutilizada com uma requisição diferente. |
| 409 | stamping_in_progress | O reenvio fica bloqueado enquanto o carimbo do PDF está pendente. |
| 409 | delivery_not_yet_released | O produto tem um atraso de entrega de downloads configurado e os arquivos do comprador ainda não foram liberados. error.details.release_at é o instante ISO 8601 da liberação; o lojista pode liberar o pedido antecipadamente com o endpoint grant-downloads. |
| 409 | notification_not_cancellable | Só uma notificação de atualização de produto na fila pode ser cancelada. Esta já começou a enviar, terminou, falhou ou foi cancelada — error.details.status diz qual. |
| 409 | app_not_installed | O Alva não tem uma sessão ativa do Shopify para a loja, geralmente porque o aplicativo foi desinstalado, então uma requisição que precisa do Shopify não pode ser executada — uma escrita de mapeamento ou uma notificação de atualização de produto cuja observação menciona um metacampo ou que envia variant_ids. Abra ou reinstale o aplicativo no admin do Shopify e tente de novo. |
| 409 | multiple_mappings_match | Um id do Shopify corresponde a mais de um mapeamento, então o Alva não consegue saber a qual você se refere. Em POST /products/{id}/notifications, error.details.ambiguous_variant_ids lista as variantes solicitadas que mais de um mapeamento atende. |
| 409 | personalized_product | O produto é personalizado. A personalização vale para o produto inteiro, então POST /mappings com shopify_variant_ids não pode adicionar a ele um mapeamento específico de variante (nada é gravado), e POST /products/{id}/notifications não pode notificar seus compradores, porque cada pedido tem seu próprio arquivo. |
| 422 | storage_quota_exceeded | O upload ou a importação excederia a cota de armazenamento. |
| 422 | key_limit_reached | A loja já possui o máximo de 25 chaves de API ativas; revogue uma primeiro. |
| 422 | withdrawal_consent_required | A loja tem o consentimento do direito de arrependimento da UE ativado e o pedido ainda não possui registro de consentimento; as URLs de download são emitidas assim que o cliente consente. |
| 422 | email_disabled | Os e-mails para clientes estão desativados nas configurações de e-mail do aplicativo. Retornado por um reenvio de e-mail de pedido, por POST /orders/{id}/assignments com send_email: true (nada é criado), por POST /products/{id}/notifications e como resultado de notify_customers em uma escrita de mapeamento (o mapeamento em si continua salvo). Ative-os e tente de novo. |
| 422 | invalid_message | A observação de atualização de produto quebrou uma regra: em branco, longa demais (também depois que suas variáveis são preenchidas), uma variável desconhecida ou não fechada, mais de cinco metacampos diferentes, um link ou endereço de e-mail (também dentro do valor de um metacampo), ou um metacampo ausente, longo demais ou de um tipo que não pode ser exibido em um e-mail. error.details.errors[] nomeia cada regra; error.details.max_length é o limite (2.000). Nada foi enviado nem escrito. Em uma escrita de mapeamento com notify_customers, só as regras sobre o próprio texto da observação recusam a escrita; um problema de metacampo é informado em data.notification depois que o mapeamento é salvo. |
| 422 | no_downloadable_content | Nenhum mapeamento alvo tem arquivos, packs ou links para anunciar; mapeamentos só com chaves e personalizados não podem ser objeto de uma atualização de produto. Com variant_ids, quando o produto tem outro mapeamento que poderia ser notificado, error.details.mapping_ids indica os mapeamentos para os quais essas variantes foram resolvidas. |
| 422 | no_eligible_recipients | Ninguém para quem enviar: nenhum comprador dos mapeamentos alvo aceita receber e-mails. error.details.opted_out_count diz quantos cancelaram a inscrição. Um mapeamento recém-criado ainda não tem compradores. |
| 429 | rate_limited | O limite de chaves de API ou de reenvios do pedido foi atingido. |
| 429 | notification_cooldown | Uma notificação de atualização de produto por produto a cada 7 dias, em todas as suas variantes e em todas as origens — ou uma campanha para o produto ainda está na fila ou enviando. Isto não é o token bucket: Retry-After pode chegar a sete dias e error.details.next_available_at é o instante em que o produto fica livre de novo. Não tente de novo automaticamente — agende a próxima chamada para next_available_at. Cancelar uma campanha não zera o limite; use dry_run para conferir uma observação antes de enviar. |
| 429 | too_many_active_notifications | A loja já tem 5 notificações de atualização de produto na fila ou enviando, somando todos os produtos e todas as origens. error.details.limit é o limite e error.details.active_notification_ids lista essas campanhas, da mais antiga para a mais recente. Não há Retry-After: consulte periodicamente GET /notifications/{id} de uma delas e tente de novo quando ela terminar. Um dry run é recusado da mesma forma; em uma escrita de mapeamento, isso é informado em data.notification. |
| 500 | internal_error | Erro inesperado do servidor. Em POST /products/{id}/notifications, todo 500 libera a Idempotency-Key, então tente de novo a mesma requisição com a mesma chave. Lá, três casos são esperados: o Shopify não conseguiu retornar os metacampos do produto para a observação, o Shopify não conseguiu confirmar os variant_ids solicitados, ou a criação esperou mais de 8 segundos atrás das outras criações da loja. Se a tentativa que falhou chegou a colocar a campanha na fila, a nova tentativa é recusada com 429 notification_cooldown em vez de iniciar uma segunda. |
Documentação da API
Isto foi útil?
Última atualização 2026-10-20