Erros, limites e paginação

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.
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 traz a descrição de cada operação.
429	A sua integração passou do limite de requisições.
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

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

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:

{
  "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

• A secret key está guardada só no seu backend.
• A sua assinatura reproduz os exemplos de validação.
• 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.