Referência

Erros

O envelope de erro, os códigos que existem e o que cada um pede que você faça.

Todas as páginas▾

Toda resposta de erro tem a mesma forma — inclusive as que nem chegaram ao seu endpoint, como JSON malformado:

 
{
  "error": {
    "code": "validation_error",
    "message": "Corpo inválido.",
    "issues": [
      { "path": "regularPriceCents", "message": "Required" }
    ]
  }
}

issues só aparece nos 422 e nomeia cada campo que falhou. É a sua superfície de depuração no dia a dia — em contraste deliberado com os 401, que são opacos de propósito e não dizem qual parte da credencial estava errada.

Todos os códigos

HTTPCódigoSignificado
400invalid_jsonO corpo não pôde ser lido como JSON (ou o Content-Type está errado).
401missing_api_keyFaltou o cabeçalho Authorization: Bearer ....
401invalid_api_keyChave não reconhecida.
401revoked_api_keyChave revogada no painel.
403store_inactiveA loja está desativada na zankh.
403subscription_suspendedAssinatura suspensa por falta de pagamento — toda rota responde isso até a fatura ser paga.
404product_not_foundProduto inexistente, ou de outra loja.
404order_not_foundPedido inexistente, ou de outra loja.
404agent_order_not_foundPedido do agente inexistente, ou de outro parceiro.
409slug_takenDuas chamadas disputaram o mesmo slug livre no mesmo instante — repita. (Slug já usado é gravado com sufixo, sem erro.)
409product_has_variantsEstoque do produto num produto com variação ativa — use PUT /v1/products/{id}/variants.
409external_ref_conflictAdoção recusada: o produto já tem outra chave, veio de um marketplace, ou a chave é de outro produto.
409variant_combination_conflictUm SKU e uma combinação apontam para variações diferentes (skus).
409product_managed_by_marketplacePUT /variants num produto importado de marketplace — a importação é dona das variações.
409email_in_useCadastro de loja: o e-mail do dono já tem conta.
409slug_in_useCadastro de parceiro: o slug já existe.
409order_already_paidCancelamento recusado — estorne pelo painel.
409agent_order_already_acceptedRecusa negada: o pedido já tinha sido aceito.
409agent_order_already_rejectedAceite negado: o pedido já tinha sido recusado e o cliente estornado.
422validation_errorCorpo, query ou caminho inválidos — veja issues (parâmetros do caminho aparecem como params.<nome>).
422unknown_categoryUm categorySlugs não existe nesta loja (slugs).
422image_fetch_failedUma foto não pôde ser copiada (index, url, reason); nada foi gravado.
422variation_type_not_standardO nome do tipo pertence a um tipo de serviço de encordoamento nesta loja.
429too_many_requestsMais de 2 chamadas copiando fotos ao mesmo tempo nesta loja — repita quando uma terminar.
500internal_errorErro inesperado do servidor. Não há nada errado com a sua requisição; tente de novo.
503image_storage_unavailableO armazenamento de fotos está indisponível; chamadas sem foto continuam funcionando.