# Erros, limites e paginação

> Como interpretar cada resposta de erro, quando tentar de novo e como paginar consultas sem estourar o limite.

Fonte: https://api.viashopmoda.com.br/docs-api/?p=guias/erros-limites-paginacao · Atualizado em 18/11/2026


## Formato das respostas

Toda resposta é JSON. Campos que podem aparecer em qualquer rota:

| Campo | Significado |
|---|---|
| `retorno` | `true` = a operação foi feita. `false` = não foi. **Sempre confira este campo**, mesmo com HTTP 200. |
| `status` | O código HTTP, repetido no corpo. |
| `msg` | Mensagem de sucesso. |
| `msg_erro` | Motivo da recusa. |
| `msg_alerta` | Aviso: a operação foi feita, mas algo merece atenção (ex.: itens descartados, vendedor não encontrado). |
| `cod_erro` | Código do erro de limite (`limite_requisicoes_dia`, `limite_requisicoes_segundo`). |

## Códigos HTTP

| HTTP | Quando | Tentar de novo? |
|---|---|---|
| `200` com `retorno: true` | Sucesso. | — |
| `200` com `retorno: false` | Recusa de regra de negócio em algumas rotas (ex.: foto já enviada, cliente já existente). | Não. Leia `msg_erro`. |
| `400` | Dados inválidos, campo faltando, registro não encontrado. | **Não** sem corrigir o envio. |
| `401` | Token inválido ou ainda não ativo. | Não. Confira o token. |
| `409` | Cadastro duplicado (ex.: `cliente/cadastrar` com CPF/e-mail já existente). | Não. Use o registro existente (`cod_cliente` vem na resposta). |
| `429` + `cod_erro: limite_requisicoes_segundo` | Mais de 1 requisição no mesmo segundo. | Sim, depois de 1 segundo. |
| `429` + `cod_erro: limite_requisicoes_dia` | Limite diário da loja atingido. | Só no dia seguinte. |
| `500` | Erro interno. | Uma vez, depois de alguns minutos. Se repetir, envie a resposta para api@viashopmoda.com.br. |

Exemplo de recusa:

```json
{
  "retorno": false,
  "status": 400,
  "msg_erro": "Objeto 'pedido' não enviado"
}
```

## Operações em lote

Rotas que recebem lista (`estoque/atualizar`, `preco/atualizar`, `cod_barras/atualizar`, `cod_externo/associar`…) processam **item a item** e respondem com o resultado de cada um:

```json
{
  "retorno": true,
  "qtd_atualizar": 3,
  "qtd_atualizados": 2,
  "qtd_nao_atualizados": 1,
  "atualizados": [ ... ],
  "nao_atualizados": [ ... ]
}
```

`retorno: true` significa que **o lote** foi processado — não que todos os itens deram certo. Sempre leia `nao_atualizados` (e `erros`, quando existir) e corrija só esses itens.

## Limites

| Limite | Valor |
|---|---|
| Requisições por segundo | **1** |
| Requisições por dia | **2.500** por loja, somando **todos os tokens** da loja |
| Itens por lote | **20** |
| Registros por página nas consultas | **20** (estoque sem filtro: 100) |

Consulte o saldo do dia com [`limites_api/consultar`](https://api.viashopmoda.com.br/docs-api/?p=recursos/limites_api/consultar&formato=md).

### Boas práticas

- Fila no ERP com no máximo 1 requisição por segundo.
- Agrupe até 20 itens por lote em vez de 20 requisições de 1 item.
- Envie só o que mudou.
- Use webhooks para saber de novidades; deixe consultas periódicas para conferência, com folga.
- Em `429` por segundo, espere e tente de novo; em `429` por dia, pare e registre.

## Paginação

Consultas com mais de 20 resultados trazem `cabecalho.paginacao`:

```json
{
  "cabecalho": {
    "paginacao": {
      "total_registros": 52,
      "limite_paginas": 20,
      "total_paginas": 3,
      "pagina_atual": 1,
      "ultima_pagina": false
    }
  }
}
```

Peça `pagina=2`, `pagina=3`… até `ultima_pagina` ser `true`. Cada página é uma requisição e conta no limite.

## Rotas assíncronas

`imagens/upload`, `pedido/associar_codexterno` e `cliente/associar_codexterno` não executam na hora: a resposta traz `automacao_id`, e o resultado final aparece em [`automacao/consultar`](https://api.viashopmoda.com.br/docs-api/?p=recursos/automacao/consultar&formato=md) (status `cadastrado`, `pendente`, `enviado` ou `erro`).
