Skip to main content
Todas as respostas de erro seguem o mesmo envelope: 
{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Invalid request payload",
    "details": [
      { "path": "items.0.sku", "message": "String must contain at most 100 character(s)" }
    ]
  }
}

​
Códigos

HTTPcodeSignificado
400validation_errorPayload mal-formado, campos faltando, valores inválidos
401unauthorizedAPI key ausente, inválida, ou revogada
403forbiddenScope insuficiente para a operação
404not_foundRecurso não existe (item, webhook, job)
409conflictConflito de estado (SKU duplicado, job já em estado terminal)
422unprocessableOperação semanticamente inválida (item sem trackStock recebendo ajuste de estoque)
429too_many_requestsRate limit excedido
500errorErro inesperado no servidor — abra ticket com o request-id

​
Request ID

Toda resposta inclui o header X-Request-Id. Inclua-o em qualquer ticket de suporte para que possamos investigar via Cloud Logging. 
X-Request-Id: 01HXYZ123ABCDEF

​
Erros parciais em bulk-upsert

POST /items/bulk-upsert não falha o lote inteiro quando 1 item dá erro. Você recebe 200 OK com cada item individualmente: 
{
  "success": true,
  "data": {
    "results": [
      { "externalId": "PROD-1", "status": "created", "voopId": "uuid-1" },
      { "externalId": "PROD-2", "status": "error", "error": "validation: sku required" }
    ],
    "summary": { "created": 1, "updated": 0, "unchanged": 0, "failed": 1 }
  }
}