ShiwakeDocs

Errors

The ApiResponse envelope, common status codes, and error detail payloads.

Every error response uses the same ApiResponse<T> envelope as a success response. Clients can parse both shapes with a single type.

Envelope shape

{
  "code": 422,
  "message": "Debits do not balance credits for currency GHS.",
  "data": null
}

Prop

Type

Decide on success by checking code is in the 200–299 range. The SDK does this for you and throws LedgerCoreException on anything else.

Common status codes

CodeWhenExample
400Malformed request body, missing required headers, invalid query parametersIdempotency-Key header is required on all mutating ledger requests.
401Missing or invalid X-Api-Key / bearer tokenInvalid API key.
403Credential is valid but tenant is disabled, or policy not satisfiedTenant is disabled.
404Resource does not exist in the current tenantAccount 'acc_01HZ...' not found.
409Conflict with existing state (duplicate code, already disabled, etc)Account with code 'CLIENT-42' already exists.
422Semantically invalid: debits ≠ credits, insufficient balance, etcSee below
429Rate limit exceededToo many requests.
500Unhandled server errorAn error occured, please try again later.

422 with detail payloads

Some 422 responses return a structured detail object in data so clients can react programmatically. The most common is insufficient balance when posting a journal entry:

{
  "code": 422,
  "message": "Insufficient balance on account 'CLIENT-42'.",
  "data": {
    "accountCode": "CLIENT-42",
    "currentBalance": 15000,
    "requestedDebit": 50000,
    "shortfall": 35000
  }
}

Prop

Type

Other 422 responses (for example, Cannot deactivate account 'CLIENT-42': ledger balance is 15000 (minor units).) return null data and rely on the message field.

Validation errors

Request body validation (missing required fields, wrong types) is performed by ASP.NET model binding before the controller runs. These still use the envelope but may include an expanded message:

{
  "code": 400,
  "message": "The Code field is required.",
  "data": null
}

Handling errors in code

try
{
    var entry = await ledger.PostJournalEntryAsync(request, idempotencyKey);
    logger.LogInformation("Posted {EntryId}", entry.Id);
}
catch (LedgerCoreException ex) when (ex.StatusCode == 422)
{
    // Parse the insufficient-balance detail if you need it
    logger.LogWarning("Posting rejected: {Message}", ex.ApiMessage);
}
catch (LedgerCoreException ex) when (ex.StatusCode == 429)
{
    // Back off and retry with the same Idempotency-Key
    await Task.Delay(TimeSpan.FromSeconds(5));
}
catch (LedgerCoreException ex)
{
    logger.LogError("Shiwake call failed: {Status}: {Message}",
        ex.StatusCode, ex.ApiMessage);
    throw;
}

Retry guidance

StatusRetry?How
400NoFix the request
401, 403NoRotate credentials or re-authenticate
404NoThe resource does not exist
409NoReconcile with existing state
422NoThe operation is semantically invalid
429YesExponential backoff with jitter, same Idempotency-Key
500, 502, 503, 504YesExponential backoff with jitter, same Idempotency-Key

Always reuse the original Idempotency-Key on retries. A fresh key on a retry is a new logical operation and may cause duplicate posts.

Edit on GitHub

Last updated on

On this page