Erros e retentativas

Quando algo falha na API da BlendFi, a resposta é sempre JSON e tem sempre o mesmo formato. Esta página mostra como ler, quais erros são seguros para retentar e como tratar request_id para suporte. Para a referência alfabética de cada code, veja o Catálogo de erros.

O formato da resposta de erro

{
  "code": "kyc_required",
  "message": "User KYC is not approved.",
  "request_id": "01KPR9F6MM8G147177J7ZQPJHG",
  "details": { /* opcional, presente em erros de validação */ }
}

Como tratar um erro

const res = await fetch(url, options);

if (!res.ok) {
  const error = await res.json();

  switch (error.code) {
    case "validation_error":
      return showFieldErrors(error.details?.issues);
    case "idempotency_key_required":
      throw new Error("chave de idempotência ausente; bug na camada de retry");
    case "rate_limit_exceeded":
      return retryAfterBackoff(error);
    case "internal_error":
      return retryWithBackoff(error);
    default:
      return reportUnexpected(error);
  }
}

const body = await res.json();
log.info({
  request_id: body.request_id,
  transaction_id: body.id,
  status: res.status,
}, "blendfi.transaction.created");

Política de retentativa

Um loop de retentativa razoável

async function withRetry(fn) {
  const MAX_ATTEMPTS = 5;
  let lastError;

  for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
    try {
      const res = await fn();
      if (res.status < 500 && res.status !== 429) return res;
      lastError = await res.json();
    } catch (networkError) {
      lastError = networkError;
    }

    const backoff = Math.min(2 ** attempt * 250, 4000);
    const jitter = Math.random() * 100;
    await sleep(backoff + jitter);
  }

  throw new Error("blendfi: retentativas esgotadas", { cause: lastError });
}

Encapsule fn() para que a mesma chave de idempotência seja reaproveitada entre as tentativas. Veja Idempotência.

Códigos que toda integração precisa tratar

A lista completa está no Catálogo de erros. Os abaixo aparecem com mais frequência e merecem código dedicado:

Códigos com sufixo _provider_unavailable (kyc_provider_unavailable, pix_provider_unavailable, etc.) sempre indicam falha transitória de upstream e são 502. Seguros para retentar.

Erros de validação em detalhe

Quando a resposta for 400 validation_error, details.issues lista cada campo com problema:

{
  "code": "validation_error",
  "message": "Request validation failed.",
  "request_id": "01KPR9F6MM8G147177J7ZQPJHG",
  "details": {
    "issues": [
      { "path": "cpf", "message": "must be 11 digits" },
      { "path": "external_id", "message": "is required" }
    ]
  }
}

path é o caminho JSON do campo problemático. Mostre essas mensagens junto aos campos do seu formulário; o cliente final agradece.

FAQ

Devo retentar em um 400 validation_error? Não. A mesma requisição falha do mesmo jeito toda vez. Corrija o corpo, gere uma chave nova e reenvie.

O code veio com um valor que eu nunca vi. O que faço? Trate como internal_error para fins de retentativa: não retente operações destrutivas; retente leituras com backoff. Abra um chamado com o request_id e nós documentamos o código ou consertamos o bug.

Meu orçamento de retentativas acabou e não vi resposta final. Qual é o estado? Para POST e PATCH, busque o recurso direto com GET usando os identificadores que você enviou. Se você usou external_id ou Idempotency-Key consistentes, o seu dado é encontrável; você só não sabe se o create original foi bem-sucedido, e a consulta esclarece.

429 não veio com retry_after_seconds. Quanto tempo eu espero? Use backoff exponencial começando em 1 segundo, com teto de 30 segundos. Em respostas degradadas o details pode vir incompleto.

Qual a diferença entre authentication_failed e missing_capability? authentication_failed (401) significa que não conseguimos identificar você (chave ruim, revogada, do ambiente errado). missing_capability (403) significa que sabemos quem você é, mas a sua chave não tem escopo para o endpoint. A primeira corrige copiando a chave certa; a segunda exige ajuste comercial.

Próximos passos

• Catálogo de erros: a lista alfabética com filtro, status, causa, recuperação.
• Idempotência: o contrato de retentativa, mesma chave, mesma resposta.
• Ambientes e limites: limites por chave e diferenças entre sandbox e produção.