Start Here

TypeScript error handling

Check ApiResponse envelopes, read Core error bodies, and handle validation and transport failures with the TypeScript SDK.

Every SDK method returns an ApiResponse<T>. The SDK does not throw on API failures. Check status before you use data.

On success, data holds the resource. On failure, status and message describe what went wrong. error holds structured Core error details when available. data may hold Core’s raw error JSON or be null.

Parse the response

Read the envelope first. Use status to classify the failure, then read the field that carries detail for that type.

interface ApiResponse<T> {
  status: number;
  message: string;
  data: T;
  error?: {
    code: string;
    message: string;
    details?: unknown;
  } | null;
}

Property	Contains
`status`	HTTP-style codes: 2xx success, 4xx client error, etc.
`data`	Success body, or Core error JSON on rejection. May be `null`.
`error`	Structured error parsed from Core’s `error_detail`. Use `error.code` for logic.
`message`	Human-readable description. For logs and UI only. Do not use for logic.

How to handle errors

Check status

Confirm success before you use data. On every call, check that status is in the 2xx range for the method you called.

const response = await blnk.Transactions.get('txn_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94');

if (response.status < 200 || response.status >= 300) {
  const errorCode = response.error?.code;

  switch (response.status) {
    case 404:
      // Resource not found: check errorCode (e.g. TXN_NOT_FOUND)
      break;
    case 401:
    case 403:
      // Auth or scope failure: check the API key
      break;
    default:
      // Log status, errorCode, and response.message
      break;
  }
  return;
}

// Use response.data

Read the error detail

Use the field that matches the failure type:

Core rejection (status is a Core HTTP error and data is set): read response.error?.code for the code Core returned.
SDK validation (status === 400 and data is null): read response.message and fix the payload before retrying.

Route on response.status when you do not need code-level logic (401, 404, 409, 5xx).

Configure transport handling

When the SDK cannot reach Core or the request times out, you get status: 500 and data: null.

Configure timeout and logging in your SDK client to investigate these failures.

Core errors

When Core rejects a request, the SDK wraps the failure in an ApiResponse. It sets status to Core’s HTTP status, message to the error message, data to Core’s JSON error body, and error to structured details parsed from error_detail.

On Core 0.15.0 and later, a rejected request looks like this:

const response = await blnk.Transactions.get('txn_missing');

// response:
{
  status: 404,
  message: 'transaction not found',
  data: {
    error: 'transaction not found',
    error_detail: {
      code: 'TXN_NOT_FOUND',
      message: 'transaction not found',
      details: {}
    }
  },
  error: {
    code: 'TXN_NOT_FOUND',
    message: 'transaction not found',
    details: {}
  }
}

The SDK exports these codes as BlnkErrorCode:

Constant	When Core returns it
`BlnkErrorCode.TXN_VALIDATION_ERROR`	Negative `amount` or `precision`, or source equal to destination
`BlnkErrorCode.GEN_CONFLICT`	Duplicate General Ledger indicator and currency (`409`)
`BlnkErrorCode.TXN_INVALID_AMOUNT`	Invalid amount (see the API error codes catalog)

Use response.status to pick the first branch (not found, auth, conflict, bad request, or server failure). Then use response.error?.code for the specific case.

Status	When it happens	What to do
`404`	Resource ID or path does not exist	Check `response.error?.code` (e.g. `TXN_NOT_FOUND`, `IDT_NOT_FOUND`)
`401` or `403`	API key, scope, or permission failure	Check the key, scopes, and whether the method requires the master key
`409`	Conflict (duplicate reference, lock, or in-progress job)	Retry only if the operation is safe to repeat
`400`	Core rejected the payload	Fix the request body before retrying
`5xx`	Core or upstream failure	Retry later and check Core logs

Client-side validation

Some methods validate input before sending a request. When validation fails, Core never receives the call.

Field	Value
`status`	`400`
`message`	Validation error string, e.g. `reference field must be a valid string`
`data`	`null`
`error`	`null`

Transport failures

When the SDK cannot reach Core or the request times out, you get status: 500, data: null, and a message describing the failure. Configure timeout and logging in Using the SDK.

When debugging transport failures, log status, message, and the endpoint you called.