Errors and retries

When something fails in the BlendFi API, the response is always JSON and always has the same shape. This guide shows you how to read it, what each code means, and which errors are safe to retry.

The error envelope

{
  "code": "invalid_transaction_state",
  "message": "Transaction cannot transition from 'buying_crypto' to 'completed'.",
  "request_id": "01KPR9F6MM8G147177J7ZQPJHG",
  "details": { /* optional, present on 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":
      // Show field errors from error.details.issues
      return showFieldErrors(error.details?.issues);
    case "idempotency_key_required":
      throw new Error("missing idempotency key — bug in our retry layer");
    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");

Retry policy

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

Wrap fn() so the same idempotency key is reused across attempts — see the Idempotency guide for why this matters.

Full error catalogue

4xx — your request

429 — rate limit

5xx — our problem

Validation errors in detail

When the response is 400 validation_error, details.issues lists every failed 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 dotted JSON path of the offending field. Show these inline next to your form fields — your end users will appreciate it.

What to read next

FAQ

Should I retry on a 400 validation_error? No. The exact same request will fail the same way every time. Fix the body, mint a new idempotency key, send again.

The code field has a value I've never seen. What do I do? Treat it as internal_error for retry purposes (don't retry destructive operations; do retry idempotent reads with backoff). Email us with the request_id and we'll either document the code or fix the bug.

My retry budget is exhausted but I haven't seen a final response. What's the state? For POST and PATCH, query the resource directly with GET using the parameters you sent. If you used the recommended external_id/Idempotency-Key patterns, your data is findable — you just don't know if the original create succeeded. The lookup tells you.

429 doesn't include a Retry-After. How long should I back off? Use exponential backoff starting at 1 second, capped at 30 seconds. We aim to always include Retry-After, but degraded responses may strip it.

What's the difference between authentication_failed and unauthorized? authentication_failed means we can't identify you (bad key). unauthorized means we know who you are but you're trying to access a resource that isn't yours (e.g. a transaction in another organization).