Começando

Erros e limites

O formato dos erros, os códigos de resposta da API e como funciona o limite de requisições de cada grupo.

Formato dos erros

Quando uma chamada dá errado, a resposta traz a lista errors, com a mensagem de cada erro em errorMessage, e o sessionGuid, que identifica a chamada:

JSON

{
  "errors": [
    { "errorMessage": "Pedido não encontrado" }
  ],
  "sessionGuid": "b28a419684c1432f23b6fddb3d748c51"
}

Guarde o sessionGuid

Registre o sessionGuid dos erros no seu sistema. Ao falar com o suporte, informe o sessionGuid, o horário da chamada e o código de resposta.

Os erros devolvidos pelo gateway, antes de a chamada chegar à API, também vêm em errors, mas sem sessionGuid. É o caso do 401 de token inválido e dos 502 e 504. Já o 401 sem corpo é explicado em Autenticação.

Códigos de resposta

Código	Quando acontece
`200`	Consulta feita com sucesso
`201`	Token gerado com sucesso na autenticação
`400`	Dados inválidos ou regra de negócio não atendida. A mensagem em `errors` diz o motivo, como "Pedido não encontrado" ou "Chave de integração inválida"
`401`	Token ausente, inválido, expirado ou enviado com `Bearer`. Veja Autenticação
`404`	Rota inexistente, com a resposta sem corpo. Confira a versão e o nome do recurso, que é sempre no singular: `/v1/empresa`, não `/v1/empresas`
`415`	Na geração do token, corpo enviado sem o header `Content-Type: application/json`. A resposta vem sem corpo
`429`	Limite de requisições do grupo atingido. Veja Limite de requisições
`500`	Erro inesperado do nosso lado. Tente de novo e, se persistir, fale com o suporte informando o `sessionGuid`
`502`, `504`	Vêm do gateway, quando a API está fora do ar ou não responde a tempo (o gateway espera até 29 segundos). Tente de novo e, se persistir, fale com o suporte

Limite de requisições

Cada grupo pode fazer até 100 requisições de uma vez e, depois disso, cerca de 100 por minuto, somando todas as integrações do grupo.

O limite funciona como um balde de fichas:

O balde de cada grupo comporta 100 fichas, e cada requisição à API gasta uma.
A cada 3 segundos, o balde recebe 5 fichas de volta, até o máximo de 100.
Na prática, você pode fazer uma rajada de até 100 requisições e depois manter cerca de 100 por minuto.

Quando o balde esvazia, a API responde 429 com o header Retry-After, que diz quantos segundos esperar. A mensagem do erro traz o mesmo número:

JSON

{
  "errors": [
    { "errorMessage": "Limite de requisições do plano atingido. Tente novamente em 3 segundos." }
  ],
  "sessionGuid": "b28a419684c1432f23b6fddb3d748c51"
}

O que gasta ficha

As chamadas aos recursos da API (GET /v1/empresa e GET /v1/pedido/{id}/aberto) de todas as integrações do grupo, inclusive as que terminam em 400.
O botão Testar dos endpoints: ele faz chamadas reais com o seu token e gasta fichas do mesmo balde.

O que não gasta ficha

Chamadas recusadas com 401.
Chamadas a rotas inexistentes (404).
A geração do token (POST /auth/integracao), que é feita em outro serviço.

Como tratar o 429

Espere os segundos do Retry-After antes de tentar de novo.
Em processamentos em lote, espace as chamadas em vez de disparar todas de uma vez: o balde repõe 5 fichas a cada 3 segundos.
Lembre que o balde é do grupo: outra integração do mesmo grupo pode estar gastando fichas ao mesmo tempo.
Se chamar a API do navegador, o seu código não consegue ler o header Retry-After, porque o CORS da API não o expõe. Use os segundos da mensagem do erro.