Erros - Voop API

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

HTTP	code	Significado
400	`validation_error`	Payload mal-formado, campos faltando, valores inválidos
401	`unauthorized`	API key ausente, inválida, ou revogada
403	`forbidden`	Scope insuficiente para a operação
404	`not_found`	Recurso não existe (item, webhook, job)
409	`conflict`	Conflito de estado (SKU duplicado, job já em estado terminal)
422	`unprocessable`	Operação semanticamente inválida (item sem trackStock recebendo ajuste de estoque)
429	`too_many_requests`	Rate limit excedido
500	`error`	Erro 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 }
  }
}