Error Handling

The error envelope

Every error response returns this JSON body. It is the exact shape on the wire — no other error dialects.

{
  "error_code": "BILL_NOT_FOUND",
  "error_type": "invalid_request",
  "error_message": "No bill exists with id bill_abc123.",
  "hint": "Verify the bill_id from a recent list call.",
  "docs_url": "https://docs.billerapi.com/errors/BILL_NOT_FOUND",
  "request_id": "d94f5e2a-8c3b-4f1e-9a7d-6b2c1e0f8a34"
}

Validation errors

A 400 VALIDATION_ERROR carries an errors array — one entry per offending field, so you can map problems straight onto a form. Each item names the field in the same snake_case you sent it.

{
  "error_code": "VALIDATION_ERROR",
  "error_type": "invalid_request",
  "error_message": "One or more request fields are invalid. See errors[] for details.",
  "hint": "Inspect errors[] for the offending fields and retry with a corrected request.",
  "docs_url": "https://docs.billerapi.com/errors/VALIDATION_ERROR",
  "request_id": "d94f5e2a-8c3b-4f1e-9a7d-6b2c1e0f8a34",
  "errors": [
    { "param": "given_name", "code": "required", "message": "given_name should not be empty" },
    { "param": "email", "code": "invalid_format", "message": "email must be an email" }
  ]
}

HTTP Status Codes

Error code reference

The error_code field is one of these stable codes. Each links to a dedicated page at https://docs.billerapi.com/errors/<code> with cause, fix, and an example. The list is additive-only.

Handling Errors

Always check the HTTP status code and parse the error envelope for details.

try {
  const response = await fetch('https://sandbox.api.billerapi.com/v1/billers', {
    headers: {
      Authorization: `Bearer ${process.env.BILLERAPI_SECRET_KEY}`,
    },
  });

  if (!response.ok) {
    const error = await response.json();
    console.error(`[${response.status}] ${error.error_code}: ${error.error_message}`);
    console.error('Fix:', error.hint, '·', error.docs_url);

    if (error.error_code === 'VALIDATION_ERROR') {
      for (const field of error.errors ?? []) {
        console.error(`  ${field.param} (${field.code}): ${field.message}`);
      }
    }

    if (error.error_type === 'rate_limit') {
      // Prefer the body field; fall back to the Retry-After header.
      const retryAfter = error.retry_after ?? response.headers.get('Retry-After');
      console.log(`Retry after ${retryAfter} seconds`);
    }
    return;
  }

  const data = await response.json();
  console.log(data);
} catch (err) {
  console.error('Network error:', err.message);
}

404 after a webhook is normal

BillerAPI’s webhook bodies are intentionally minimal — they carry the envelope plus a small data.object with the resource ID and a few routing keys. To get the full resource you call GET /v1/<resource>/<id> after handling the webhook.

That follow-up GET can return 404 Not Found even though you just received an event for the resource. This is a normal consequence of two facts:

• Webhook delivery is asynchronous; minutes can pass between the event being emitted and your handler running.
• Some resources are short-lived (a link can be disconnected, a request-to-link can be cancelled, a bill can be re-extracted with a new id).

Treat 404 as “gone is gone”: log the event id and return 200 OK from your webhook endpoint. Do not return non-2xx — that triggers BillerAPI to retry the same webhook, which will hit the same 404 on the next attempt and burn your retry budget. The state the event reflected (e.g. link.disconnected) is still actionable from the envelope alone.

async function handleBillCreated(envelope) {
  const billId = envelope.data.object.id;
  const res = await fetch(`https://api.billerapi.com/v1/bills/${billId}`, {
    headers: { Authorization: `Bearer ${linkScopedToken}` },
  });

  if (res.status === 404) {
    // Resource gone between webhook fan-out and our follow-up GET.
    // Acknowledge so we are not retried; we already know the bill id.
    logger.info('bill_gone_at_consume_time', { event_id: envelope.id, bill_id: billId });
    return; // caller returns 200 OK
  }

  if (!res.ok) throw new Error(`unexpected ${res.status}`);
  await persistBill(await res.json());
}

Related

• Error code reference — a dedicated page per error code
• Feedback errors — the FEEDBACK_* codes
• Rate Limits — rate limit policy and retry strategies
• Authentication — API key and bearer token auth
• Idempotency — webhook dedupe by event.id