Erros e Limites

A API usa códigos HTTP padrão e retorna erros em formato JSON consistente.

Formato do erro

Todos os erros retornam um objeto com statusCode, message e error:

Erro 401

{
  "statusCode": 401,
  "message": "Invalid or expired API key",
  "error": "Unauthorized"
}

Erro 403

{
  "statusCode": 403,
  "message": "Scope required: employees:write",
  "error": "Forbidden"
}

Erro 400 (validação)

{
  "statusCode": 400,
  "message": ["type must be one of the following values: ENTRY, EXIT"],
  "error": "Bad Request"
}

Códigos de status

Status	Significado	Ação recomendada
`200`	OK	Sucesso. Processar a resposta.
`201`	Created	Recurso criado. O objeto criado está no body.
`204`	No Content	Operação concluída sem corpo de resposta.
`400`	Bad Request	Dados inválidos. Verificar os campos obrigatórios e formatos.
`401`	Unauthorized	API Key ausente, inválida, expirada ou revogada. Verifique o header x-api-key.
`403`	Forbidden	Chave válida mas sem o escopo necessário. Gere uma nova chave com o escopo correto.
`404`	Not Found	Recurso não encontrado ou não pertence ao tenant.
`429`	Too Many Requests	Rate limit excedido. Aguarde e tente novamente. Veja o header Retry-After.
`500`	Internal Server Error	Erro no servidor. Tente novamente. Se persistir, contate o suporte.

Rate Limiting

A API aceita até 60 requisições por minuto por chave de API. Quando o limite é excedido, a resposta tem status 429.

💡

Para operações em lote (ex: importar muitos colaboradores), implemente um retry com backoff exponencial ao receber 429.

Exemplo de retry com backoff

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status !== 429) {
      return response;
    }

    if (attempt === maxRetries) throw new Error('Rate limit excedido após retries');

    const wait = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
    await new Promise(r => setTimeout(r, wait));
  }
}

Boas práticas

• Timestamps com fuso: Sempre envie timestamps com offset de fuso horário (ex: 2026-03-16T08:00:00-03:00) para evitar erros de conversão.
• Escopos mínimos: Crie chaves separadas para cada integração com apenas os escopos necessários.
• Rotação de chaves: Defina expiração nas chaves e crie um processo de rotação periódica.
• Paginação: Para tenants com muitos colaboradores, use sempre page e limit para evitar respostas muito grandes.
• TLS: Use sempre HTTPS. Conexões HTTP não são aceitas em produção.