Errors and retries

When something fails in the BlendFi API, the response is always JSON and always has the same shape. This page shows you how to read it, which errors are safe to retry, and how to use request_id with support. For the alphabetical reference of every code, see the Errors catalog.

The error response shape

{
  "code": "kyc_required",
  "message": "User KYC is not approved.",
  "request_id": "01KPR9F6MM8G147177J7ZQPJHG",
  "details": { /* optional, present in validation errors */ }
}

How to handle an error

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("missing idempotency key, retry-layer bug");
    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");

Retry policy

A reasonable retry loop

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: retries exhausted", { cause: lastError });
}

Wrap fn() so the same idempotency key is reused across attempts. See Idempotency.

Codes every integration must handle

The full list lives in the Errors catalog. The ones below show up most often and deserve dedicated handling:

Codes ending in _provider_unavailable (kyc_provider_unavailable, pix_provider_unavailable, etc.) always indicate transient upstream failure and are 502. Safe to retry.

Validation errors in detail

When the response is 400 validation_error, details.issues lists each problematic field:

{
  "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 is the JSON path of the offending field. Show those messages next to your form fields; the end customer thanks you.

FAQ

Should I retry on 400 validation_error? No. The same request will fail the same way every time. Fix the body, generate a new key, resend.

The code came with a value I've never seen. What do I do? Treat as internal_error for retry purposes: don't retry destructive operations; retry reads with backoff. Open a ticket with the request_id and we'll either document the code or fix the bug.

My retry budget is exhausted and I never saw a final response. What's the state? For POST and PATCH, fetch the resource directly with GET using the identifiers you sent. If you used consistent external_id or Idempotency-Key, your data is findable; you just don't know if the original create succeeded, and the lookup resolves that.

429 came without retry_after_seconds. How long do I wait? Use exponential backoff starting at 1 second, capped at 30 seconds. In degraded responses details may come incomplete.

What's the difference between authentication_failed and missing_capability? authentication_failed (401) means we cannot identify you (bad key, revoked, wrong environment). missing_capability (403) means we know who you are, but your key has no scope for the endpoint. The first you fix by copying the right key; the second requires a commercial adjustment.

Next steps

• Errors catalog: the alphabetical list with filter, status, cause, recovery.
• Idempotency: the retry contract, same key, same response.
• Environments and rate limits: per-key limits and sandbox vs production differences.