# Erros, limites e paginação

> Status HTTP de erro, limites de requisição por api key, cabeçalhos X-RateLimit e paginação por limit e offset.

URL canônica: https://apis.cortecloud.com.br/docs/comecando/erros-limites-paginacao/

## Erros {#erros}

| Status | Situação |
| --- | --- |
| `400` | O corpo ou a query string não passou na validação da rota (campo obrigatório ausente, tipo errado, valor fora do permitido). |
| `401` | Falha de autenticação. As causas estão em [Autenticação](https://apis.cortecloud.com.br/docs/comecando/autenticacao.md#quando-a-autenticacao-falha). |
| `403`, `404`, `409`, `422` | Erro de negócio da rota: recurso não encontrado, status do serviço que não permite a operação, vendedor inexistente, central sem permissão. Cada guia lista os erros das suas rotas, e a [Referência da API](https://apis.cortecloud.com.br/docs/swagger) traz a descrição de cada operação. |
| `429` | A sua integração passou do [limite de requisições](https://apis.cortecloud.com.br/docs/comecando/erros-limites-paginacao.md#limites-de-requisicao). |
| `5xx` | Falha ao processar a requisição na Serrabits, inclusive `504` quando a resposta passa do tempo limite. Pode ser transitória: repita com espera crescente e um número limitado de tentativas, e escreva para suporte@serrabits.com.br se persistir. |

Algumas rotas também respondem `500` ou `502` quando o Cortecloud recusa a operação; nesses casos, repetir não resolve, e o guia da rota diz o que corrigir. O corpo da resposta de erro traz uma mensagem com o motivo. Use o status HTTP para decidir o tratamento e a mensagem para registrar e diagnosticar.

## Limites de requisição {#limites-de-requisicao}

Os limites são por api key e contados separadamente em cada rota:

- **5 requisições por segundo** na maioria das rotas.
- **1 requisição a cada 5 segundos** nas rotas que operam sobre a coleção inteira:
  - listagem e atualização em lote de materiais: `GET`, `PUT` e `PATCH` em `/materials/boards`, `/materials/edges` e `/materials/components`;
  - cópia entre centrais: `POST /materials/boards/cross-sync`, `POST /materials/edges/cross-sync` e `POST /materials/components/cross-sync`;
  - listagem de serviços: `GET /services`.

Toda resposta traz os cabeçalhos:

| Cabeçalho | Conteúdo |
| --- | --- |
| `X-RateLimit-Limit` | Quantas requisições a rota aceita na janela. |
| `X-RateLimit-Remaining` | Quantas ainda restam na janela atual. |
| `X-RateLimit-Reset` | Segundos até a janela recomeçar. |

Acima do limite, a resposta é `429` com `Retry-After` em segundos. Espere esse tempo antes de repetir a requisição. Trate `429` separado dos erros de negócio: a requisição não foi processada e pode ser repetida sem efeito colateral.

Ao percorrer uma listagem paginada numa rota de 1 requisição a cada 5 segundos, espere entre uma página e a próxima. Para atualizar muitos materiais, prefira uma chamada em lote a várias chamadas individuais.

## Paginação {#paginacao}

As listagens (`GET /services`, `GET /materials/boards`, `GET /materials/edges`, `GET /materials/components`) aceitam `limit` e `offset` na query string:

- `limit`: itens por página, no máximo `500`; o padrão também é `500`.
- `offset`: quantos itens pular; o padrão é `0`.

A resposta traz os itens em `resource` e a paginação em `meta`:

```json
{
  "resource": [],
  "meta": {
    "count": 1234,
    "next": 500
  }
}
```

Para a próxima página, envie em `offset` o valor de `meta.next` da resposta anterior. `meta.next` nulo indica a última página.

## Antes de ir para produção {#antes-de-ir-para-producao}

- A secret key está guardada só no seu backend.
- A sua assinatura reproduz os [exemplos de validação](https://apis.cortecloud.com.br/docs/comecando/autenticacao.md#valide-a-sua-implementacao).
- Toda requisição envia `x-company-internal-code`.
- A integração lê os cabeçalhos `X-RateLimit-*` e trata `429` à parte dos erros de negócio.
- As listagens seguem `meta.next` até ele vir nulo.