Amazon Ads Write Recovery — Titanos MCP

Quando usar / When to Use This Skill

Use esta skill quando o usuário / Use this skill when the user:

• Is applying Ads mutations and a write failed mid-way
• Needs dry-run, idempotency, or readback before/after writes
• Wants to avoid duplicate campaigns or recover a partial write

Objetivo

Evitar que agentes dupliquem campanhas, keywords, targets ou product ads quando um write via Titanos MCP falha no meio.

Use esta skill para qualquer mutação Amazon Ads com create_resources, update_resources ou delete_resources.

Regra principal

Depois de erro em write, nunca reexecute o mesmo lote às cegas.

Faça readback primeiro. Erro 502/timeout pode acontecer depois de a Amazon ter criado parte dos recursos.

Antes do write

1. Confirmar conta:
   • connection_id
   • profile_id
   • marketplace
2. Confirmar escopo/schemas:
   • list_resource_types
   • tools/list se disponível
3. Rodar dry_run: true.
4. Mostrar payload e impacto ao usuário.
5. Receber confirmação explícita.
6. Executar dry_run: false em lotes pequenos.

Lote seguro

Use no máximo 5 itens por batch.

Exemplo de idempotency keys:

bkza-mocho-20260705-campaigns-1
bkza-mocho-20260705-adgroups-1
bkza-mocho-20260705-productads-1
bkza-mocho-20260705-keywords-1
bkza-mocho-20260705-targets-1
bkza-mocho-20260705-negatives-1

Não reutilize a mesma idempotency_key com payload diferente. Se precisar mudar payload, use nova chave e faça readback antes.

Sequência de criação SP recuperável

Como lidar com erro

Caso 1: INTERNAL_ERROR (502) ou timeout

Ação:

1. Pare.
2. Faça readback por nome/ID exato.
3. Compare o plano com o que já existe.
4. Continue apenas os recursos faltantes.
5. Registre o erro real para o dev.

Nunca diga "não criou nada" sem readback.

Caso 2: IDEMPOTENCY_CONFLICT (409)

Causa:

• mesma idempotency_key usada com payload diferente.

Ação:

1. Readback do estado atual.
2. Gerar nova idempotency_key para o payload corrigido.
3. Criar só o que falta.

Caso 3: VALIDATION_ERROR (400)

Ação:

1. Ler erro de campo/caminho.
2. Comparar com schema do list_resource_types.
3. Confirmar se payload do MCP precisa ser flat ou nested.

IMPORTANTE — update_resources exige wrapper changes:

O payload de update deve ter a estrutura:

{
  "resource_type": "sp_keywords",
  "resources": [
    {
      "keyword_id": "<keyword_id>",
      "changes": {
        "bid": 2.0
      }
    }
  ],
  "dry_run": true
}

NÃO passe campos soltos (bid, state) no nível do resource — eles devem estar dentro de changes. Passar bid solto causa VALIDATION_ERROR (400).

O mesmo padrão vale para sp_campaigns (changes: { daily_budget, state, name }) e sp_targets (changes: { bid, state }).

Exemplos reais de formato correto:

update_resources sp_campaigns:
  { campaign_id: "<campaign_id>", changes: { daily_budget: 65 } }     → ✅
  { campaign_id: "<campaign_id>", changes: { state: "PAUSED" } }    → ✅
  { campaign_id: "<campaign_id>", changes: { name: "TEST" } }       → ✅

update_resources sp_keywords:
  { keyword_id: "<keyword_id>", changes: { bid: 1.55 } }            → ✅
  { keyword_id: "<keyword_id>", changes: { state: "PAUSED" } }     → ✅

update_resources sp_targets:
  { target_id: "<target_id>", changes: { bid: 1.55 } }             → ✅
  { target_id: "<target_id>", changes: { state: "PAUSED" } }      → ✅

Outros exemplos de validação:

• sp_campaigns: start_date precisa ISO YYYY-MM-DD.
• sp_product_ads: Amazon exige sku; ASIN sozinho pode falhar.
• sp_keywords: use keyword_text + match_type, não expression de target.
• sp_targets: use expression com ASIN_SAME_AS, não keyword.

Caso 4: RESOURCE_NOT_FOUND (404)

Possíveis causas:

• campaign/ad group ID não existe ou ainda não propagou.
• ad group pertence a outra campanha/profile.
• ASIN target inválido para marketplace.
• recurso criado mas readback ainda está atrasado.

Ação:

1. Readback de campaign.
2. Readback de ad group.
3. Aguardar curto intervalo se acabou de criar.
4. Validar ASIN/marketplace.
5. Tentar 1 item isolado com nova idempotency key.

Checklist de recovery

Quando algo falhar, produza esta tabela:

Modelo de mensagem para dev

Inclua sempre:

MCP version:
resource_type:
dry_run:
idempotency_key:
connection_id:
profile_id:
payload mínimo que falhou:
retorno bruto:
readback depois do erro:

Exemplo:

create_resources sp_keywords falha no write real.
Dry-run OK.
Payload:
{ ... }
Retorno: INTERNAL_ERROR (502)
Readback: keyword não apareceu no ad group.

Modelo de resposta para usuário

Se parcial:

Parcialmente criado:
- campaigns: 3/3
- ad groups: 3/3
- product ads: 6/6
Pendente por erro backend:
- keywords: 0/21
- targets: 0/6
Ação: enviei payload/erro para dev; vou continuar só dessas etapas quando corrigido.

Se concluído:

Concluído e verificado:
- campaigns: 3
- ad groups: 3
- product ads: 6
- keywords: 21
- targets: 6
- negativos: 16
Budget diário máximo: R$120

Anti-padrões

• Repetir batch inteiro depois de 502.
• Usar mesma idempotency key com payload diferente.
• Criar product ads sem SKU.
• Continuar para keywords antes de confirmar product ads.
• Dizer que criou sem readback.
• Misturar profile/marketplace.
• Fazer write sem aprovação explícita.
• Passar campos soltos no update_resources sem wrapper changes.

Status por versão (testado 2026-07-06, MCP 1.42.2 pós-fix)

update_resources — ✅ funcionando

Corrigido em 2026-07-06. O bug era duplo:

1. id_field no registry estava target_id em vez de keyword_id para sp_keywords — corrigido.
2. Schema Zod estava .strict() rejeitando campos extras — corrigido para .passthrough().
3. Payload precisa do wrapper changes — isso é by design, não bug.

delete_resources — ✅ funciona para sp_keywords

Confirmado em produção: keywords deletadas com sucesso usando:

{ "keyword_id": "<keyword_id>" }

Reports com days — ✅ funciona (assíncrono)

Os reports com days retornam status PENDING e geram o relatório em background (~45-120s). Não é mais 502.

Também funcionam com start_date/end_date no formato YYYY-MM-DD.

ask_ads_report_analyst — ⚠️ scope sensitivity

• ✅ Funciona sem connection_id/profile_id (usa default da org)
• ❌ Falha com connection_id + profile_id (retorna VALIDATION_ERROR (400))

list_ads_recommendations — ✅ funcionando (graceful)

Corrigido em 2026-07-06. Se a Amazon retorna 403 (comum em contas BR), o endpoint retorna [] com nota explicativa em vez de 502.

get_bid_guidance — ✅ funcionando

Corrigido em 2026-07-06. A Amazon exigia o campo strategy no payload. Agora o campo é enviado com default CONVERSION_OPPORTUNITIES.

Pode retornar suggested_bid: null para keywords sem histórico suficiente — isso é normal, não bug.

DSP — ❌ requer conta agency

Todas as funções DSP retornam erro para contas seller. DSP requer perfil agency.

get_targets para PAT — ⚠️

get_targets retorna keywords[] corretamente para campanhas KW, mas targets[] vem vazio para campanhas PAT mesmo quando o create retorna DUPLICATE_VALUE (provando que o target existe). O bug pode ser no filtro adGroupIdFilter do endpoint /sp/targets/list.

create_resources sp_product_ads — formato correto

✅ Funciona:  { campaign_id, ad_group_id, sku, state }
✅ Funciona:  { campaign_id, ad_group_id, asin, state }
✅ Funciona:  { campaign_id, ad_group_id, sku, asin, state }
❌ Falha:     { campaignId, adGroupId, sku, state }  (camelCase)

Usar sempre snake_case nos payloads de create.