> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blnkfinance.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Error Handling
> Check three-value returns, read Core error bodies, and handle validation and transport failures with the Go SDK.
export const CtaCallout = props => {
const {title, buttonLabel, href, trackingEvent, buttonTarget, rel = "noopener noreferrer", children} = props;
const handleCtaClick = () => {
if (typeof window === "undefined" || !trackingEvent) {
return;
}
try {
window.dispatchEvent(new CustomEvent("blnk:docs-cta", {
detail: {
name: trackingEvent,
href
}
}));
} catch {}
try {
window.posthog?.capture?.(trackingEvent, {
href
});
} catch {}
const gaPayload = {
cta_href: href
};
try {
window.gtag?.("event", trackingEvent, gaPayload);
} catch {}
try {
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
event: trackingEvent,
...gaPayload
});
} catch {}
};
const isExternal = typeof href === "string" && (/^https?:\/\//i).test(href);
const target = buttonTarget ?? (isExternal ? "_blank" : undefined);
const linkRel = isExternal ? rel : undefined;
return ;
};
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.
```go theme={"system"}
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 value | Contains |
| :--------------- | :-------------------------------------------------------------------------------------------------------------- |
| Result | Decoded success body. May be zero when `err` is set. |
| `*http.Response` | HTTP status, headers, and metadata. May be `nil` when validation fails before a request is sent. |
| `error` | Core HTTP failure (`*ApiErrorResponse`), client-side validation error, JSON decode error, or transport failure. |
***
## How to handle errors
Confirm success before you use the result. On every call, check that `err` is `nil`.
```go Error handling theme={"system"}
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
```
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).
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](/sdks/go/start/using-the-sdk#timeouts-and-retries) 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:
```go 404 Not Found expandable theme={"system"}
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.
| Status | When it happens | What to do |
| :------------- | :------------------------------------------------------- | :-------------------------------------------------------------------------------------------------- |
| `404` | Resource ID or path does not exist | Parse `error_detail.code` from `apiErr.Body` when available (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. 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](/changelog/v15-migration) and [API error codes](/advanced/error-codes).
***
## Client-side validation
Some methods validate input before sending a request. When validation fails, Core never receives the call.
| Field | 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](/reference/create-ledger) 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](/sdks/go/start/using-the-sdk#timeouts-and-retries) to investigate these failures.
When debugging transport failures, log the error, the endpoint you called, and any HTTP status returned before the failure.
***
## Related docs
Timeouts, retries, and logging.
Error codes, inflight queuing, and reconciliation changes.
Install the SDK and create your first transaction.
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](mailto:support@blnkfinance.com) or [join our Discord community](https://discord.gg/7WNv94zPpx).
Sign up and manage your ledger with our back-office dashboard. You can invite teammates to collaborate and manage your ledger operations directly from the dashboard.