Start Here

Go error handling

Check three-value returns, read structured Core error codes, and handle validation and transport failures with the Go SDK.

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.

What each return value holds

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

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
}

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

How to handle errors

txn, resp, err := client.Transaction.Get("txn_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94")
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

What Core sends on rejection

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

{
  "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.

The SDK exports these codes as constants:

When Core returns only a flat "error" string with no error_detail, the SDK sets ErrorDetail.Code to "UNKNOWN".

Use apiErr.Status to pick the first branch (not found, auth, conflict, bad request, or server failure). Then use apiErr.ErrorDetail.Code for the specific case.

Client-side validation

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