Erros

Todo erro vem no mesmo formato:

{
  "error": {
    "type": "invalid_request",
    "code": "idempotency_key_reused",
    "message": "Esta chave de idempotência (o cabeçalho Idempotency-Key ou o idempotency_key do MCP) já foi usada numa chamada diferente. Use uma chave nova para cada escrita.",
    "fields": [{ "field": "variants.0.price", "message": "Informe o preço" }],
    "request_id": "6f1c2a4e-..."
  }
}

type diz o que fazer, e corresponde ao status.
code é estável, em inglês: é por ele que o programa decide. Códigos novos podem aparecer sem mudar a versão.
message é em português, para gente ler. Não compare o texto: ele pode mudar.
fields vem nos erros de validação, com o campo e o motivo, e nos lotes de estoque e de preço, com o item recusado (items.3.delta). O campo de uma lista leva a posição: variants.1.compare_at_price é a segunda variante.
request_id é o mesmo do cabeçalho Denaryx-Request-Id, que vem em toda resposta. Mande ao suporte quando algo der errado.
Alguns erros trazem detalhes próprios: conflicts no 409 file_conflict e problems no 422 theme_has_errors (ver Temas), e content_conflicts no 409 revert_conflict do desfazer pelo servidor MCP (ver Servidor MCP).

`type`	Status	Quando	Tentar de novo?
`authentication_error`	401	O token falta, não existe, foi revogado ou venceu.	Não, sem trocar o token.
`permission_error`	403	O token não tem o escopo da rota, ou é um login do CLI fora dos temas.	Não, sem marcar o escopo no painel.
`not_found`	404	O recurso não existe nesta loja, ou a rota não existe nesta versão (`route_not_found`).	Não.
`conflict`	409	O estado mudou no meio (outra escrita, uma chave de idempotência em andamento).	Sim, depois de ler de novo.
`invalid_request`	400, 422	Algum campo está errado, ou a chave de idempotência foi reaproveitada.	Não, sem corrigir a chamada.
`rate_limited`	429	Chamadas demais.	Sim, depois do `Retry-After`.
`api_error`	500, 503	Erro do nosso lado (500), ou a API está ocupada ou a consulta passou do prazo (503).	Sim, com espera crescente; no 503, depois do `Retry-After`.

Os 401 vêm com o cabeçalho WWW-Authenticate: Bearer.

Alguns códigos:

`code`	Status	Quando
`invalid_json`	400	O corpo não é um JSON válido.
`payload_too_large`	413	O corpo passou de 1 MB, ou um arquivo passou do tamanho máximo da rota. Mande em partes.
`missing_scope`	403	O token não tem o escopo da rota.
`cli_session_not_allowed`	403	O login do CLI pela conta vale só nos temas: para o resto, use o token de uma integração.
`store_suspended`	403	A loja está suspensa pela Denaryx: a API volta quando ela for reativada. O motivo está no painel da loja.
`file_conflict`	409	Um arquivo do tema mudou desde a leitura: leia de novo e grave com o checksum de agora.
`theme_read_only`	409	O código de um tema da plataforma é só para leitura: crie um fork.
`theme_connected`	409	O tema está conectado a uma branch do GitHub, ou é a prévia de um pull request: o código muda pelo push.
`theme_has_errors`	422	O código do tema tem erro e não pode ser publicado.
`development_theme`	409	O tema de desenvolvimento (do CLI ou da prévia de um pull request) não é publicado.
`development_theme_limit`	409	O limite de temas de desenvolvimento (5 por integração ou pessoa, 30 por loja) chegou.
`invalid_idempotency_key`	400	O cabeçalho `Idempotency-Key` não tem de 1 a 255 caracteres.
`idempotency_key_reused`	422	A chave de idempotência já foi usada numa chamada diferente.
`idempotency_key_in_use`	409	A primeira chamada com a mesma chave ainda está em andamento.
`duplicate_sku`	409	O SKU já está em outra variante da loja.
`duplicate_barcode`	409	O código de barras já está em outra variante da loja.
`duplicate_handle`	409	O `handle` já é de outro produto, marca ou página da loja, ou de outra coleção no mesmo lugar da árvore.
`insufficient_inventory`	409	O ajuste deixaria algum estoque abaixo de zero (ver Estoque e preço).
`variant_not_found`	422	Um item do lote aponta para uma variante que não existe nesta loja.
`inventory_not_tracked`	422	Um item do lote de estoque é de um produto sem controle de estoque (ver Estoque e preço).
`assembly_already_linked`	409	A coleção ou o produto já usa outra montagem (ver Montagens).
`image_url_not_allowed`	400	O endereço da foto leva a uma rede interna (ver Produtos).
`image_download_failed`	422	Não foi possível baixar a foto do endereço.
`try_on_rejected`	422	O arquivo do provador não serve (ver Provador virtual).
`model_url_not_allowed`	400	O endereço do GLB do provador leva a uma rede interna.
`model_download_failed`	422	Não foi possível baixar o GLB do endereço.