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▾
Comece aqui
Inteligência artificial
Referência
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
| HTTP | Código | Significado |
|---|---|---|
| 400 | invalid_json | O corpo não pôde ser lido como JSON (ou o Content-Type está errado). |
| 401 | missing_api_key | Faltou o cabeçalho Authorization: Bearer .... |
| 401 | invalid_api_key | Chave não reconhecida. |
| 401 | revoked_api_key | Chave revogada no painel. |
| 403 | store_inactive | A loja está desativada na zankh. |
| 403 | subscription_suspended | Assinatura suspensa por falta de pagamento — toda rota responde isso até a fatura ser paga. |
| 404 | product_not_found | Produto inexistente, ou de outra loja. |
| 404 | order_not_found | Pedido inexistente, ou de outra loja. |
| 404 | agent_order_not_found | Pedido do agente inexistente, ou de outro parceiro. |
| 409 | slug_taken | Duas chamadas disputaram o mesmo slug livre no mesmo instante — repita. (Slug já usado é gravado com sufixo, sem erro.) |
| 409 | product_has_variants | Estoque do produto num produto com variação ativa — use PUT /v1/products/{id}/variants. |
| 409 | external_ref_conflict | Adoção recusada: o produto já tem outra chave, veio de um marketplace, ou a chave é de outro produto. |
| 409 | variant_combination_conflict | Um SKU e uma combinação apontam para variações diferentes (skus). |
| 409 | product_managed_by_marketplace | PUT /variants num produto importado de marketplace — a importação é dona das variações. |
| 409 | email_in_use | Cadastro de loja: o e-mail do dono já tem conta. |
| 409 | slug_in_use | Cadastro de parceiro: o slug já existe. |
| 409 | order_already_paid | Cancelamento recusado — estorne pelo painel. |
| 409 | agent_order_already_accepted | Recusa negada: o pedido já tinha sido aceito. |
| 409 | agent_order_already_rejected | Aceite negado: o pedido já tinha sido recusado e o cliente estornado. |
| 422 | validation_error | Corpo, query ou caminho inválidos — veja issues (parâmetros do caminho aparecem como params.<nome>). |
| 422 | unknown_category | Um categorySlugs não existe nesta loja (slugs). |
| 422 | image_fetch_failed | Uma foto não pôde ser copiada (index, url, reason); nada foi gravado. |
| 422 | variation_type_not_standard | O nome do tipo pertence a um tipo de serviço de encordoamento nesta loja. |
| 429 | too_many_requests | Mais de 2 chamadas copiando fotos ao mesmo tempo nesta loja — repita quando uma terminar. |
| 500 | internal_error | Erro inesperado do servidor. Não há nada errado com a sua requisição; tente de novo. |
| 503 | image_storage_unavailable | O armazenamento de fotos está indisponível; chamadas sem foto continuam funcionando. |