Start here

0.15.0 Migration Guide

Review error codes, removed response fields, and queued inflight commit and void before you upgrade to v0.15.0.

This guide covers the changes you need to review when upgrading to Blnk v0.15.0. Most integrations can upgrade without major changes. Review this guide carefully if your app:

• Branches on HTTP status codes
• Parses error message text
• Reads rate, currency_multiplier, or modification_ref from API responses
• Sends rate on create-transaction requests for cross-currency FX
• Expects inflight commit or void requests to return APPLIED or VOID immediately
• Reads reconciliation status directly from the start response

At a glance

Structured error_detail added

Error responses now include a structured error_detail object. The existing error field is still returned, so existing integrations that read error continue to work.

{
  "error": "transaction not found",
  "error_detail": {
    "code": "TXN_NOT_FOUND",
    "message": "transaction not found",
    "details": {}
  }
}

For new error handling logic, branch on error_detail.code. Do not branch on error, errors, or error_detail.message. These fields are human-readable and may change between releases. See API error codes for the errors catalog.

HTTP status codes corrected

Several errors that previously returned 400 now return more specific HTTP statuses. The response body still includes error and error_detail. The main change is the HTTP status code returned with the response.

Review any logic that:

• Treats every failed request as 400
• Branches only on HTTP status codes
• Does not read error_detail.code

NOT_FOUND: message prefix removed

Error messages no longer include the NOT_FOUND: prefix. If your integration checks for this prefix, update it to use error_detail.code.

if (error.message.startsWith("NOT_FOUND:")) {
  // handle not found
}

if (body.error_detail?.code === "TXN_NOT_FOUND") {
  // handle not found
}

This is safer because error_detail.code is stable. Message text is meant for display and may change between releases.

rate, currency_multiplier, and modification_ref removed

Blnk no longer stores or returns these fields:

Request rate no longer converts amounts between currencies. The destination is credited the same precise amount as the source debit. If you need multi-currency movement, model FX explicitly with separate balances and legs. See Currency exchange.

Inflight commit and void are queued by default

Single and bulk inflight commit and void requests now go through the queue by default. This means the action is processed asynchronously instead of being applied immediately in the request cycle.

By default, the response returns the transaction with:

{
  "transaction_id": "txn_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94",
  "status": "INFLIGHT",
  "queued": true
}

The transaction remains INFLIGHT until the worker processes the queued commit or void. A second queued commit or void for the same transaction returns 409 Conflict. To keep the previous synchronous behavior, send skip_queue: true in the request body. Use this when your app needs the request to return an immediate APPLIED or VOID response.

curl -X PUT "http://YOUR_BLNK_INSTANCE_URL/transactions/inflight/{transaction_id}" \
  -H "X-Blnk-Key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "commit",
    "skip_queue": true
  }'

const response = await blnk.Transactions.updateStatus('{transaction_id}', {
  status: 'commit',
  skip_queue: true,
});

transaction, _, _ := client.Transaction.Update("{transaction_id}", blnkgo.UpdateStatus{
    Status: blnkgo.InflightStatusCommit,
    SkipQueue: true,
})

response = blnk.transactions.update_status("{transaction_id}", {
  "status": "commit",
  "skip_queue": True,
})

ApiResponse<JsonNode> response = blnk.transactions().updateStatus(
    "{transaction_id}",
    UpdateTransactionStatus.create()
        .status("commit")
        .skipQueue(true));

Reconciliation response changed

Start reconciliation and Instant reconciliation no longer return run status, match counts, or timestamps in the start response. Both endpoints now return only reconciliation_id.

Here’s the new flow:

1. Start the reconciliation and save the returned reconciliation_id.
2. Handle reconciliation.completed or reconciliation.failed on your webhook endpoint.
3. Read status, match counts, and timestamps from the webhook payload.

See Reconciliations and Supported events.

Request and item limits

Blnk Core 0.15.0 adds per-endpoint item limits and configurable request size caps:

Configurable JSON body and upload size caps are documented in Server and security configuration.

Recommended upgrade checklist

Before upgrading to v0.15.0:

• Replace message-text parsing with error_detail.code.
• Review any logic that depends on HTTP status codes.
• Remove reads of rate, currency_multiplier, and modification_ref. Stop using request rate for FX; use currency exchange instead.
• Update inflight commit and void flows to handle queued responses or use skip_queue: true to keep existing synchronous behavior.
• Update reconciliation flows to handle reconciliation.completed and reconciliation.failed webhooks instead of reading status from the start response.