Referência de Erros

Todos os códigos de status HTTP retornados pela API de Integração Fhinck e como interpretá-los.

Shape padrão de resposta

Toda resposta da API — com sucesso ou erro — inclui o campo booleano err:

Sucesso

{
  "err": false,
  "result": { ... }
}

Erro

{
  "err": true,
  "message": "Descrição do erro"
}

Códigos HTTP

Status	Nome	Quando ocorre	Ação recomendada
200	OK	Requisição processada com sucesso.	Verificar `err: false` antes de consumir `result`.
400	Bad Request	Campo `key` ausente, nulo ou com formato inválido.	Verificar se a `key` está presente e não foi truncada.
401	Unauthorized	A `key` não pôde ser descriptografada ou resulta em empresa nula.	Solicitar nova `key` ao time Fhinck.
422	Unprocessable Entity	Campos obrigatórios ausentes ou com formato inválido (ex.: data fora do padrão, tipo errado).	Verificar o schema do endpoint na documentação específica.
429	Too Many Requests	Limite de requisições atingido.	Aguardar o período de cooldown indicado e retentar.
500	Internal Server Error	Falha inesperada no servidor Fhinck.	Retentar após alguns segundos. Se persistir, contato@fhinck.com.

Exemplos de resposta por código

400 — Bad Request

JSON — key ausente

{
  "err": true,
  "message": "Parametro key não informado ou inválido",
  "code": "MISSING_KEY"
}

401 — Unauthorized

JSON — key inválida

{
  "err": true,
  "message": "Parametro key não informado ou inválido",
  "code": "INVALID_KEY"
}

422 — Unprocessable Entity

JSON — campos ausentes

{
  "err": true,
  "message": "Campos obrigatórios ausentes: user, reqMinutes",
  "code": "MISSING_REQUIRED_FIELDS"
}

429 — Too Many Requests

JSON — rate limit

{
  "err": true,
  "message": "Rate limit excedido. Aguarde 1 minuto e retente.",
  "retryAfter": 60
}

500 — Internal Server Error

JSON — erro interno

{
  "err": true,
  "message": "Erro interno ao processar a requisição",
  "code": 500
}

Tratamento recomendado

Implemente sempre verificação do campo err antes de consumir a resposta:

JavaScript

const res = await fetch('https://integrations.fhinck.com/masterData', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ key: process.env.FHINCK_KEY, data: { employees: [] } })
});

const data = await res.json();

if (data.err) {
  switch (res.status) {
    case 400:
    case 401:
      throw new Error('Chave de integração inválida');
    case 422:
      throw new Error(`Dados inválidos: ${data.message}`);
    case 429:
      // retentar com backoff exponencial
      break;
    case 500:
      throw new Error('Erro interno Fhinck — tente novamente');
    default:
      throw new Error(data.message || 'Erro desconhecido');
  }
}

// Sucesso
console.log(data.result);

Campo err vs. HTTP status

Alguns endpoints de leitura retornam HTTP 200 mesmo quando não há dados, com err: false e result: []. Sempre cheque o campo err em vez de confiar apenas no status HTTP.

Nunca ignore o campo err. Um endpoint pode retornar HTTP 200 com err: true em casos legados de erros de negócio.