Skip to main content
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
  • Expects inflight commit or void requests to return APPLIED or VOID immediately
  • Reads reconciliation status directly from the start response

​
At a glance

ChangeWho is affected?What changed
Structured error_detail addedMost integrations are not affectedError responses now include error_detail.code, error_detail.message, and error_detail.details. The existing error field is still returned.
HTTP status codes correctedIntegrations that branch on old HTTP statusesSome errors now return more specific statuses, such as 404, 409, 423, and 500.
NOT_FOUND: message prefix removedIntegrations that parse error message textError messages no longer include the NOT_FOUND: prefix.
Inflight commit and void are queued by defaultIntegrations that expect immediate APPLIED or VOID responsesCommit and void requests now return a queued response by default.
Reconciliation start response changedIntegrations that read reconciliation status from the start responseStart endpoints return only reconciliation_id. Handle reconciliation.completed and reconciliation.failed webhooks for results.
Per-endpoint item limitsIntegrations that send large bulk or reconciliation requestsBulk create and instant reconciliation: max 10,000 items per request. Bulk commit and void: max 100 transactions.
Request and upload size capsIntegrations with large JSON bodies or file uploadsConfigurable caps apply to JSON request bodies and multipart uploads. See Server and security configuration.
Transaction hash chain (optional)Operators who want ledger-wide tamper detectionNew opt-in global hash chain; disabled by default. Enable in config and run blnk verify-chain. See Transaction hashing.

​
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 documentation 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
ConditionBeforeNow
Resource not found400404
Duplicate transaction reference400409
Inflight already committed or already voided400409
Identity field already tokenized400409
Tokenization disabled400403
API key create or list request missing owner when using the master key401400
Hook infrastructure failures400500
Database backup failures400500
Lock contention400423
Unclassified internal failures400500 (sanitized message)

​
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
}
This is safer because error_detail.code is stable. Message text is meant for display and may change between releases.

​
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
}

​
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:
EndpointMax per request
Bulk transactions10,000 transactions
Instant reconciliation10,000 external transactions
Bulk commit inflight / Bulk void inflight100 transactions
Configurable JSON body and upload size caps are documented in Server and security configuration.
Before upgrading to v0.15.0:
  • Replace message-text parsing with error_detail.code.
  • Review any logic that depends on HTTP status codes.
  • 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.

​
Need help?

We are very happy to help you make the most of Blnk, regardless of whether it is your first time or you are switching from another tool. To ask questions or discuss issues, please contact us or join our Discord community.