> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voop.work/llms.txt
> Use this file to discover all available pages before exploring further.

# Erros

> Formato padrão de erros da API

Todas as respostas de erro seguem o mesmo envelope:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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 }
  }
}
```