Error Handling

Every SDK method returns three values: the result, the HTTP response, and an error. Check err before you use the result. When err is nil, the result holds the decoded response. When err is set, the result is empty and you should handle the failure.

Only NewClient panics when the base URL is missing. SDK methods return errors for API and validation failures.

What each return value holds

txn, resp, err := client.Transaction.Get("txn_f482a1b3-6c2d-4e89")

Return value	Contains
Result (`txn`)	Decoded success body. Zero or `nil` when `err` is set.
`*http.Response` (`resp`)	HTTP status, headers, and metadata. `nil` when validation fails before a request is sent.
`error` (`err`)	Core HTTP failure (`*ApiErrorResponse`), client-side validation error, JSON decode error, or transport failure.

After you confirm err == nil, use the result and optionally log resp.StatusCode.

Core error types

When Core rejects a request, the SDK wraps the failure in *blnkgo.ApiErrorResponse. Use errors.As to read structured fields instead of parsing message text.

type ApiErrorDetail struct {
	Code    string
	Message string
	Details interface{}
}

type ApiErrorResponse struct {
	Status      int
	Message     string
	LegacyError string
	ErrorDetail *ApiErrorDetail
	Body        []byte
}

Field	Description
`Status`	HTTP status code from Core (for example `404`).
`Message`	HTTP status text (for example `"404 Not Found"`).
`LegacyError`	Flat `"error"` string from Core when present.
`ErrorDetail`	Structured details parsed from `error_detail`. Read `ErrorDetail.Code` for routing.
`Body`	Raw JSON error payload from Core.

The SDK also exports blnkgo.AsApiErrorResponse(err) as a shortcut for errors.As.

How to handle errors

Check err

On every call, confirm err is nil before you use the result.

Error handling

txn, resp, err := client.Transaction.Get("txn_f482a1b3-6c2d-4e89")
if err != nil {
	var apiErr *blnkgo.ApiErrorResponse
	if errors.As(err, &apiErr) {
		switch apiErr.Status {
		case http.StatusNotFound:
			// Check apiErr.ErrorDetail.Code (e.g. TXN_NOT_FOUND)
		case http.StatusUnauthorized, http.StatusForbidden:
			// Check the API key and scopes
		default:
			// Log apiErr.Status and apiErr.ErrorDetail.Code
		}
	}
	return err
}

// Use txn

Read the error detail

Use the field that matches the failure:

Core rejection: errors.As matches *ApiErrorResponse. Read apiErr.ErrorDetail.Code for logic. Use apiErr.Status when you only need broad handling (401, 404, 409, 5xx).
SDK validation: plain error before any HTTP call. Read err.Error() and fix the payload before retrying.

See API error codes for the full list of codes Core returns and what each one means.

Handle transport failures

When the SDK cannot reach Core or the request times out, you get a network or timeout error from the HTTP client. Configure timeout and logging in your SDK client.

What Core sends on rejection

When Core rejects a request, the response body looks like this:

404 Not Found

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

The SDK maps that JSON into ApiErrorResponse. Read apiErr.ErrorDetail.Code in your app, not the message string. Message text can change between releases. When Core returns only a flat "error" string with no error_detail, the SDK sets ErrorDetail.Code to "UNKNOWN".

Status	When it happens	What to do
`404`	Resource ID or path does not exist	Check `apiErr.ErrorDetail.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

Do not match exact error message strings in application logic. Prefer apiErr.ErrorDetail.Code for routing and apiErr.ErrorDetail.Message for user-facing text only.

Client-side validation

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

Return value	Value
Result	Zero value (`nil` for pointers)
`*http.Response`	`nil`
`error`	Validation message, e.g. `reference field must be a valid string`

Each Core API lists required fields for that call.

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.

Start Here

Ledgers

Ledger balances

Transactions

Reconciliation

Identities

Metadata

Search

What each return value holds

Core error types

How to handle errors

What Core sends on rejection

Client-side validation

Need help?

​What each return value holds

​Core error types

​How to handle errors

​What Core sends on rejection

​Client-side validation

​Need help?

What each return value holds

Core error types

How to handle errors

What Core sends on rejection

Client-side validation

Need help?