Erros e retentativas

Quando algo falha na API da BlendFi, a resposta é sempre JSON e tem sempre o mesmo formato. Este guia mostra como ler, o que cada code significa e quais erros são seguros para retentar.

O envelope de erro

{
  "code": "invalid_transaction_state",
  "message": "Transaction cannot transition from 'buying_crypto' to 'completed'.",
  "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":
      // Mostra erros de campo a partir de error.details.issues
      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);
  }
}

log.info({
  request_id: res.headers.get("x-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 reusada entre as tentativas — veja o guia de Idempotência para entender por quê.

Catálogo completo de erros

4xx — sua requisição

429 — limite de taxa

5xx — problema nosso

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 — seus usuários finais vão agradecer.

O que ler em seguida

FAQ

Devo retentar num 400 validation_error? Não. A mesma requisição vai falhar do mesmo jeito toda vez. Corrija o corpo, gere uma chave de idempotência nova, envie de novo.

O campo 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 idempotentes com backoff). Manda e-mail pra gente com o request_id e a gente documenta o código ou conserta o bug.

Meu orçamento de retentativas acabou e eu não vi resposta final. Qual o estado? Para POST e PATCH, busque o recurso direto com GET usando os parâmetros que você enviou. Se você usou os padrões recomendados de external_id/Idempotency-Key, seu dado é encontrável — você só não sabe se o create original deu certo. A busca te conta.

429 não veio com Retry-After. Quanto tempo eu espero? Use backoff exponencial começando em 1 segundo, com teto de 30 segundos. A gente sempre tenta incluir Retry-After, mas respostas degradadas podem omitir.

Qual a diferença entre authentication_failed e unauthorized? authentication_failed significa que a gente não consegue identificar você (chave ruim). unauthorized significa que a gente sabe quem você é mas você está tentando acessar um recurso que não é seu (por exemplo, uma transação de outra organização).