Skip to main content
When Agatabo returns an error, it usually means one of a small set of well-understood problems that have straightforward solutions. This page collects the seven most frequently encountered errors, explains exactly why they happen, and tells you what to do to fix them. Find the error message you are seeing in the accordions below.
Error messages in Agatabo are returned in JSON format in the response body. If you are using the UI, the message is displayed in a red alert banner. If you are calling the API directly, check the message field in the response JSON.
Error message: "You don't have permission to perform this action"HTTP status: 403 ForbiddenWhat causes it: Your account does not have the permission required for the operation you are attempting. Every action in Agatabo maps to a specific resource:action permission (e.g., loans:write, savings:write, periods:close). If none of your assigned roles includes that permission, the request is rejected.A variation of this error — “You can only access your own data” — means you have the correct permission but only at SELF scope, and you are trying to access another member’s data.How to fix it:
  1. Identify the specific operation that failed and look up the required permission in the Permissions Matrix.
  2. Contact your organization’s Administrator and ask them to add the required permission to one of your existing roles, or assign you a role that already includes it.
  3. Confirm you are logged in with the correct account. If you have multiple accounts (e.g., a personal member account and an operator account), make sure you are using the one with the right permissions.
  4. After the Administrator updates your roles, log out and log back in to ensure your session reflects the new permissions.
Prevention: When setting up new staff accounts, use the Permissions Matrix to select the appropriate built-in role configuration before the person begins work. Do not wait until they hit an error to discover a missing permission.
Error message: "Transaction date is in a closed period"HTTP status: 400 Bad RequestWhat causes it: You are trying to record, edit, or delete a transaction with a date that falls within an accounting period that has already been closed. Once a period is closed, all transactions in that interval are locked and cannot be changed.Common scenarios:
  • Entering a deposit dated last month after the monthly close was already run
  • Correcting a loan payment with the original transaction date
  • Recording a late-reported expense from a previous period
How to fix it: Option A — Change the transaction date (most common): Set the transaction date to today’s date or another date in the current open period. This is the appropriate approach for the vast majority of situations — the transaction is simply being recorded late.Option B — Undo the period close (use with caution): If the transaction genuinely must be recorded with the historical date and the amount is material, an Administrator with periods:close permission can undo the most recent close using POST /period-closing/undo. After the correction is made, re-run the period close checklist and close the period again.Note that you can only undo the most recent close — you cannot reopen an arbitrary historical period.Prevention: Complete all transaction recording before running the period close checklist. If you regularly discover late transactions after closing, consider building a 2–3 day buffer between the period end date and the close execution date.
Error message: "Insufficient balance"HTTP status: 400 Bad RequestWhat causes it: The transaction you are attempting would result in a negative balance in an account that is not permitted to go negative. This error can occur in three common contexts:
  1. Savings withdrawal — the withdrawal amount exceeds the member’s current savings balance
  2. Expense payment — the organization’s bank account does not have enough funds to cover the expense
  3. Loan disbursement from savings — a fee or advance interest deduction would bring the member’s savings balance below zero
How to fix it:
  1. Double-check the transaction amount — data entry errors (extra zeros, decimal misplacement) are the most common cause.
  2. For a savings withdrawal: View the member’s current savings balance via their account page or GET /organization-users/{id}. If the balance is genuinely insufficient, either reduce the withdrawal amount or wait until the member makes additional deposits.
  3. For an expense payment: Check the organization’s bank account balance in Agatabo. If the balance is correct, verify that sufficient funds exist in the bank before recording the expense.
  4. If you need to override the balance check for a loan disbursement in a specific exceptional circumstance, include "skipNegativeBalanceCheck": true in the POST /loans request body — but use this flag sparingly and document the reason.
Prevention: Run the Bank Reconciliation step during your pre-close checklist to ensure your cash balances are always up to date. Train treasurers to verify member balances before processing withdrawal requests.
Error message: "Savings can only be recorded for organization users with member role" or "Member not found"HTTP status: 404 Not Found or 400 Bad RequestWhat causes it: You are trying to record a deposit, withdrawal, or loan for an organization user who does not have the “member” role assigned. In Agatabo, an organization user is not a financial participant until the member role is explicitly granted — no role means no savings ledger account, and without a savings ledger account, no financial operations are possible.This error most commonly occurs immediately after creating a new organization user if the role assignment step was skipped.How to fix it:
  1. Confirm that the organization user exists: GET /organization-users/{id}.
  2. Check their current role assignments: GET /organization-users/{id}/role-assignments.
  3. If the member role is missing, assign it: POST /organization-users/{id}/role-assignments with the correct roleDefinitionId for your organization’s member role.
  4. Verify that the savings ledger account was created: GET /organization-users/{id} and check that savingsLedgerAccountId is non-null.
  5. Retry the original operation.
Prevention: Follow the New Member Onboarding workflow checklist, which includes role assignment as a mandatory step before any financial setup.
Error message: "Organization user already has an active or defaulted loan" or "Principal exceeds max allowed" or "Insufficient security coverage"HTTP status: 409 Conflict or 400 Bad RequestWhat causes it: One or more of Agatabo’s loan eligibility rules has not been met. The specific message tells you exactly which rule failed:
MessageRule Violated
"Organization user already has an active or defaulted loan"Member already has a loan in ACTIVE or DEFAULTED status
"Principal exceeds max allowed from max loan percentage rule"Loan amount > (member savings × max_loan_percentage)
"Loan period cannot exceed X month(s)"Period exceeds the organization’s max_period setting
"Insufficient security coverage"Total security value < principal amount
How to fix it:For an existing active loan: Wait until the current loan is fully repaid (status = COMPLETED). If the loan is uncollectible, process a formal default via POST /loans/{id}/default before issuing a new one.For max loan percentage: Either reduce the principal amount, or ask the member to increase their savings balance before reapplying. An Administrator can also update the max_loan_percentage setting in Organization Settings if your policies allow for a higher ratio.For insufficient securities: Add additional guarantors, increase collateral coverage, require a higher savings lien, or reduce the principal to match the available security value.For max period: Reduce the loan term, or request an Administrator update the max_period setting if your policies permit longer terms.Prevention: Complete Stage 1 (Pre-Loan Preparation) of the Loan Disbursement Workflow before creating any loan. Running through the eligibility checklist offline takes five minutes and prevents 100% of eligibility-related errors.
Error message: "x-idempotency-key header is required" or "Duplicate transaction detected"HTTP status: 400 Bad Request or 409 ConflictWhat causes it:
  • Missing key: The x-idempotency-key header was not included in a mutation request. All financial write operations require this header.
  • Duplicate key: The same idempotency key has already been used successfully in your organization. Agatabo enforces uniqueness per organization — once a key is used, it can never be reused for a different transaction.
This protection prevents duplicate transactions from network timeouts, accidental double-clicks, or form resubmissions.How to fix it:For a missing key error: Add the x-idempotency-key header to the request with a unique value. Use crypto.randomUUID() or another UUID v4 generator.For a duplicate key error:
  1. First, check whether the original transaction was recorded successfully by looking at the relevant transaction list (e.g., the member’s deposit history or the loan portfolio).
  2. If the original did succeed: Do not retry. The transaction exists — display a success message to the user.
  3. If the original did not succeed (e.g., it failed with a validation error before being saved): You may safely retry with the same idempotency key after fixing the validation issue.
  4. If you want to record a new, separate transaction: Generate a fresh idempotency key.
Prevention: See Idempotency for a complete implementation guide with TypeScript examples, retry logic, and best practices.
Error message: "Network error", request timeout, or no response receivedWhat causes it: A network error means the HTTP request did not complete successfully. The root cause could be:
  • Your internet connection dropped or became unstable
  • The Agatabo server took longer than your client’s timeout threshold to respond
  • A proxy, firewall, or VPN interrupted the request
  • A temporary server-side issue (rare)
The key question with network errors: Did the request reach the server and get processed, or did it fail before the server saw it? You cannot always tell from the client side.How to fix it:
  1. Check your connection: Confirm you can load other websites or the Agatabo dashboard.
  2. For read requests (GET): Simply retry — GET requests are safe to repeat.
  3. For write requests (POST/PUT/DELETE):
    • Do NOT immediately resubmit with a new idempotency key. First, check whether the transaction was already recorded.
    • Navigate to the relevant section (member’s transaction history, loan list, etc.) and look for the transaction you were trying to create.
    • If the transaction is there: It succeeded. Do not resubmit.
    • If the transaction is not there: Retry with the same idempotency key. Because the original request either failed before being saved or was rejected, using the same key is safe and will not create a duplicate.
  4. Wait 60 seconds before retrying to allow any transient server load to resolve.
  5. If the problem persists for more than 10 minutes, contact Agatabo support with the timestamp and the operation you were attempting.
Prevention: Implement retry logic with exponential backoff and idempotency key reuse for all write operations. The Idempotency guide includes a complete TypeScript implementation with this pattern.

Permissions Matrix

Look up which permission is required for any operation

Monthly Closing Checklist

Resolve closed-period errors with the correct undo procedure

Idempotency

Prevent and handle duplicate transaction errors

New Member Onboarding

Avoid “member not found” errors with the complete onboarding flow