Skip to main content
Every SDK method returns three values: the result, the HTTP response, and an error. Check err before you use the result. On success, the result holds the resource and resp.StatusCode reflects Core’s HTTP status. On failure, err describes what went wrong. For Core HTTP errors, the SDK wraps the response in *blnkgo.ApiErrorResponse.
Only NewClient panics when the base URL is missing. SDK methods return errors for API and validation failures.

​
Parse the return values

Read the error first. Use resp.StatusCode for logging and metrics after you confirm success. 
txn, resp, err := client.Transaction.Get("txn_f482a1b3-6c2d-4e89")
if err != nil {
	var apiErr *blnkgo.ApiErrorResponse
	if errors.As(err, &apiErr) {
		fmt.Printf("API error %d: %s\n", apiErr.Status, string(apiErr.Body))
	}
	return err
}

// Use txn
fmt.Printf("HTTP status: %d\n", resp.StatusCode)
Return valueContains
ResultDecoded success body. May be zero when err is set.
*http.ResponseHTTP status, headers, and metadata. May be nil when validation fails before a request is sent.
errorCore HTTP failure (*ApiErrorResponse), client-side validation error, JSON decode error, or transport failure.

​
How to handle errors

1

Check err

Confirm success before you use the result. On every call, check that err is nil.
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:
			// Resource not found
		case http.StatusUnauthorized, http.StatusForbidden:
			// Auth or scope failure: check the API key
		default: // Log apiErr.Status and string(apiErr.Body)
		}
	}
	return err
}

// Use txn
2

Read the error detail

Use the field that matches the failure type:
  • Core rejection (errors.As matches *ApiErrorResponse): read apiErr.Status and parse apiErr.Body as JSON when you need structured fields such as error_detail.code.
  • SDK validation (plain error before any HTTP call): read err.Error() and fix the payload before retrying.
Route on apiErr.Status when you do not need code-level logic (401, 404, 409, 5xx).
3

Configure transport handling

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 to investigate these failures.

​
Core errors

When Core rejects a request, the SDK wraps the failure in *ApiErrorResponse. It sets Status to Core’s HTTP status, Message to the HTTP status text, and Body to Core’s raw JSON error payload. On Core 0.15.0 and later, a rejected request looks like this:
404 Not Found
txn, resp, err := client.Transaction.Get("txn_missing")
if err != nil {
	var apiErr *blnkgo.ApiErrorResponse
	if errors.As(err, &apiErr) {
		// apiErr:
		//   Status:  404
		//   Message: "404 Not Found"
		//   Body:    []byte(`{"error":"transaction not found","error_detail":{"code":"TXN_NOT_FOUND","message":"transaction not found","details":{}}}`)
		//
		// Parse error_detail.code from string(apiErr.Body) when you need code-level routing.
	}
}
Parse error_detail.code from apiErr.Body when you need code-level routing. Treat message strings as display text; Core may change wording between releases. On older Core versions, error_detail.code may be absent from the body.
StatusWhen it happensWhat to do
404Resource ID or path does not existParse error_detail.code from apiErr.Body when available (e.g. TXN_NOT_FOUND, IDT_NOT_FOUND)
401 or 403API key, scope, or permission failureCheck the key, scopes, and whether the method requires the master key
409Conflict (duplicate reference, lock, or in-progress job)Retry only if the operation is safe to repeat
400Core rejected the payloadFix the request body before retrying
5xxCore or upstream failureRetry later and check Core logs
Do not match exact error message strings in application logic. Message text can change. Prefer error_detail.code from apiErr.Body for routing and message strings for user-facing text only. See the 0.15.0 migration guide and API error codes.

​
Client-side validation

Some methods validate input before sending a request. When validation fails, Core never receives the call.
FieldValue
ResultZero value (nil for pointers)
*http.Responsenil
errorValidation message, e.g. reference field must be a valid string
Each Core API lists required fields for that call.

​
Transport failures

When the SDK cannot reach Core or the request times out, you get a network or timeout error from http.Client. Configure timeout and logging in your SDK client to investigate these failures. When debugging transport failures, log the error, the endpoint you called, and any HTTP status returned before the failure.

Using the SDK

Timeouts, retries, and logging.

0.15.0 migration

Error codes, inflight queuing, and reconciliation changes.

Quick start

Install the SDK and create your first transaction.

Changelog

Go SDK releases and version history.

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