Todas as respostas de erro da API Dyvit seguem um formato padronizado. Esta página documenta a estrutura do payload de erro, os códigos possíveis, os limites de requisição por plano e a estratégia recomendada de retry.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "O campo 'cpf' é obrigatório.",
    "field": "cpf",
    "statusCode": 400
  }
}

O campo field é opcional e aparece apenas em erros de validação. O code é uma string constante que pode ser usada para tratamento programático.

---

---

---

Para lidar com erros transitórios (429 e 500), recomendamos exponential backoff com jitter. Exemplo em Node.js:

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

    if (res.ok) return res.json();

    if (res.status === 429 || res.status >= 500) {
      const baseDelay = Math.pow(2, attempt) * 1000;
      const jitter = Math.random() * 1000;
      const delay = baseDelay + jitter;

      console.log(
        `Tentativa ${attempt + 1} falhou (${res.status}). ` +
        `Aguardando ${Math.round(delay)}ms...`
      );

      await new Promise((r) => setTimeout(r, delay));
      continue;
    }

    // Erros 4xx (exceto 429) não devem ser retentados
    const error = await res.json();
    throw new Error(`${error.error.code}: ${error.error.message}`);
  }

  throw new Error("Número máximo de tentativas excedido.");
}