Error Codes Catalog

Bilko Error Codes Catalog 
 
 Project: Bilko
 Version: 1.0
 Date: 2026-02-24
 Status: Specification
 Applies to: apps/api/ — all modules 
 
 
 Overview 
 All Bilko API errors follow a consistent JSON structure. Every error response includes: 
 
 An HTTP status code 
 A machine-readable BILKO-XXXX error code 
 A human-readable message (in the organization's configured language) 
 Optional field-level details for validation errors 
 
 Error code ranges by module: 
 
 
 
 Range 
 Module 
 
 
 
 
 BILKO-1xxx 
 Authentication 
 
 
 BILKO-2xxx 
 Organizations 
 
 
 BILKO-3xxx 
 Invoices 
 
 
 BILKO-4xxx 
 Expenses 
 
 
 BILKO-5xxx 
 Banking 
 
 
 BILKO-6xxx 
 Reports 
 
 
 BILKO-7xxx 
 Contacts 
 
 
 BILKO-8xxx 
 Settings & Accounts 
 
 
 BILKO-9xxx 
 General / Cross-cutting 
 
 
 
 
 Error Response Schema 
 All error responses use this structure: 
 interface ErrorResponse {
 error: {
 code: string // e.g., "BILKO-1001"
 message: string // Human-readable, localized
 details?: Record<string, string[]> // Field-level validation errors (422 only)
 requestId?: string // Trace ID for support (production)
 }
}
 
 Examples: 
 // Authentication error
{
 "error": {
 "code": "BILKO-1001",
 "message": "Pogrešan email ili lozinka.",
 "requestId": "req_01H9X3K5P2M7N8Q4R6S9T0V1W2"
 }
}

// Validation error (422) with field details
{
 "error": {
 "code": "BILKO-9003",
 "message": "Validacija nije uspjela.",
 "details": {
 "email": ["Email adresa nije ispravna."],
 "password": ["Lozinka mora imati najmanje 8 znakova.", "Lozinka mora sadržavati barem jedan broj."]
 },
 "requestId": "req_01H9X3K5P2M7N8Q4R6S9T0V1W2"
 }
}
 
 
 HTTP Status Codes 
 
 
 
 HTTP Code 
 Meaning 
 When Used 
 
 
 
 
 200 OK 
 Successful read or update 
 GET, PUT, PATCH 
 
 
 201 Created 
 Resource successfully created 
 POST (creates new record) 
 
 
 204 No Content 
 Successful deletion 
 DELETE, POST /logout 
 
 
 400 Bad Request 
 Request is well-formed but semantically invalid 
 Business rule violations (not validation) 
 
 
 401 Unauthorized 
 Missing, expired, or invalid authentication 
 No token, expired JWT, wrong credentials 
 
 
 403 Forbidden 
 Authenticated but insufficient permissions 
 Role lacks access to endpoint or action 
 
 
 404 Not Found 
 Resource does not exist within organization scope 
 Record not found or belongs to different org 
 
 
 409 Conflict 
 Resource already exists 
 Duplicate email, duplicate invoice number 
 
 
 413 Payload Too Large 
 Upload exceeds size limit 
 File uploads over 10MB (receipt) or 5MB (CSV) 
 
 
 422 Unprocessable Entity 
 Zod schema validation failed 
 Invalid field types, missing required fields 
 
 
 429 Too Many Requests 
 Rate limit exceeded 
 Auth: 5/min; writes: 10–50/min; reads: 100/min 
 
 
 500 Internal Server Error 
 Unexpected server-side error 
 Unhandled exception, DB error 
 
 
 503 Service Unavailable 
 External dependency unavailable 
 SendGrid, ECB API, Cloudflare R2 down 
 
 
 
 
 Retry Guidance 
 
 
 
 Error Code 
 HTTP 
 Retry? 
 Strategy 
 
 
 
 
 BILKO-1003 
 401 
 Yes 
 Refresh access token via POST /auth/refresh , then retry 
 
 
 BILKO-9005 
 429 
 Yes 
 Wait until Retry-After header value (seconds), then retry 
 
 
 BILKO-9006 
 500 
 Yes 
 Exponential backoff: 1s, 2s, 4s — max 3 retries 
 
 
 BILKO-9007 
 503 
 Yes 
 Exponential backoff: 2s, 5s, 10s — max 3 retries 
 
 
 All 4xx except above 
 — 
 No 
 Fix request before retrying — these are client errors 
 
 
 BILKO-1001 
 401 
 No 
 Wrong credentials — do not retry automatically 
 
 
 BILKO-3011 
 500 
 Yes 
 SendGrid transient failure — retry once after 5s 
 
 
 
 Retry-After header: Always present on 429 responses. Value is seconds to wait. 
 
 Module: Authentication (1xxx) 
 BILKO-1001 — Invalid Credentials 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 401 
 
 
 Trigger 
 POST /auth/login — email not found or password does not match bcrypt hash 
 
 
 Retry 
 No 
 
 
 
 {
 "error": {
 "code": "BILKO-1001",
 "message": "Pogrešan email ili lozinka."
 }
}
 
 
 BILKO-1002 — Account Disabled 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 403 
 
 
 Trigger 
 POST /auth/login — user has isActive = false 
 
 
 Retry 
 No — contact support 
 
 
 
 {
 "error": {
 "code": "BILKO-1002",
 "message": "Vaš nalog je deaktiviran. Kontaktirajte podršku."
 }
}
 
 
 BILKO-1003 — Access Token Expired 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 401 
 
 
 Trigger 
 Any authenticated request — JWT exp claim is in the past 
 
 
 Retry 
 Yes — refresh token first via POST /auth/refresh , then retry original request 
 
 
 
 {
 "error": {
 "code": "BILKO-1003",
 "message": "Sesija je istekla. Osvježite token."
 }
}
 
 
 BILKO-1004 — Invalid Token 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 401 
 
 
 Trigger 
 Any authenticated request — JWT signature invalid or malformed 
 
 
 Retry 
 No — re-authenticate 
 
 
 
 {
 "error": {
 "code": "BILKO-1004",
 "message": "Token nije ispravan. Molimo prijavite se ponovo."
 }
}
 
 
 BILKO-1005 — No Authentication Token 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 401 
 
 
 Trigger 
 Any authenticated endpoint called without Authorization: Bearer <token> header 
 
 
 Retry 
 No — add token 
 
 
 
 {
 "error": {
 "code": "BILKO-1005",
 "message": "Autentifikacija je obavezna."
 }
}
 
 
 BILKO-1006 — Refresh Token Invalid or Expired 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 401 
 
 
 Trigger 
 POST /auth/refresh — cookie missing, token blacklisted, or expired 
 
 
 Retry 
 No — force full re-login 
 
 
 
 {
 "error": {
 "code": "BILKO-1006",
 "message": "Sesija je istekla. Molimo prijavite se ponovo."
 }
}
 
 
 BILKO-1007 — Auth Rate Limit Exceeded 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 429 
 
 
 Trigger 
 POST /auth/login or POST /auth/register — 5+ requests in 60 seconds from same IP 
 
 
 Retry 
 Yes — after Retry-After header value (900 seconds / 15 min lockout) 
 
 
 
 {
 "error": {
 "code": "BILKO-1007",
 "message": "Previše pokušaja prijave. Pokušajte ponovo za 15 minuta."
 }
}
 
 Response headers: 
 Retry-After: 900
X-RateLimit-Limit: 5
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1740399600
 
 
 BILKO-1008 — Email Already Registered 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 409 
 
 
 Trigger 
 POST /auth/register — email already exists in users table 
 
 
 Retry 
 No — use different email or reset password 
 
 
 
 {
 "error": {
 "code": "BILKO-1008",
 "message": "Email adresa je već registrirana."
 }
}
 
 
 BILKO-1009 — Weak Password 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 422 
 
 
 Trigger 
 POST /auth/register or PUT /auth/password — password fails strength requirements 
 
 
 Retry 
 No — fix password 
 
 
 
 {
 "error": {
 "code": "BILKO-1009",
 "message": "Lozinka ne zadovoljava sigurnosne zahtjeve.",
 "details": {
 "password": [
 "Lozinka mora imati najmanje 8 znakova.",
 "Lozinka mora sadržavati barem jedno veliko slovo.",
 "Lozinka mora sadržavati barem jedan broj."
 ]
 }
 }
}
 
 
 BILKO-1010 — Two-Factor Authentication Required 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 403 
 
 
 Trigger 
 POST /auth/login — user has twoFactorEnabled = true , 2FA code not provided 
 
 
 Retry 
 No — submit TOTP code via POST /auth/verify-2fa 
 
 
 
 {
 "error": {
 "code": "BILKO-1010",
 "message": "Potrebna je dvofaktorska autentifikacija.",
 "details": {
 "requiresTwoFactor": ["true"]
 }
 }
}
 
 
 BILKO-1011 — Invalid 2FA Code 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 401 
 
 
 Trigger 
 POST /auth/verify-2fa — TOTP code incorrect or expired (outside 30s window) 
 
 
 Retry 
 No — request new code from authenticator app 
 
 
 
 {
 "error": {
 "code": "BILKO-1011",
 "message": "Kod za verifikaciju nije ispravan ili je istekao."
 }
}
 
 
 BILKO-1012 — Invalid Invite Token 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 401 
 
 
 Trigger 
 User follows invite link after it has expired (7 days) or already been used 
 
 
 Retry 
 No — request new invitation 
 
 
 
 {
 "error": {
 "code": "BILKO-1012",
 "message": "Pozivnica je nevažeća ili je istekla."
 }
}
 
 
 Module: Organizations (2xxx) 
 BILKO-2001 — Organization Not Found 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 404 
 
 
 Trigger 
 Organization ID in JWT does not exist in database (account deleted while token still valid) 
 
 
 
 {
 "error": {
 "code": "BILKO-2001",
 "message": "Organizacija nije pronađena."
 }
}
 
 
 BILKO-2002 — Invalid Currency Code 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 422 
 
 
 Trigger 
 PUT /organization — baseCurrency is not one of EUR , RSD , BAM , HRK 
 
 
 
 {
 "error": {
 "code": "BILKO-2002",
 "message": "Neispravna valuta. Podržane valute: EUR, RSD, BAM, HRK.",
 "details": {
 "baseCurrency": ["Vrijednost mora biti jedna od: EUR, RSD, BAM, HRK."]
 }
 }
}
 
 
 BILKO-2003 — Invalid Language Code 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 422 
 
 
 Trigger 
 PUT /organization — language is not one of sr , bs , hr 
 
 
 
 {
 "error": {
 "code": "BILKO-2003",
 "message": "Neispravni jezički kod. Podržani jezici: sr, bs, hr.",
 "details": {
 "language": ["Vrijednost mora biti jedna od: sr, bs, hr."]
 }
 }
}
 
 
 BILKO-2004 — Cannot Change Base Currency 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 400 
 
 
 Trigger 
 PUT /organization — attempting to change baseCurrency when transactions already exist 
 
 
 
 {
 "error": {
 "code": "BILKO-2004",
 "message": "Osnovna valuta ne može se promijeniti jer već postoje finansijske transakcije."
 }
}
 
 
 BILKO-2005 — User Not Found in Organization 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 404 
 
 
 Trigger 
 PUT /users/:id/role or DELETE /users/:id — user UUID not in caller's organization 
 
 
 
 {
 "error": {
 "code": "BILKO-2005",
 "message": "Korisnik nije pronađen u ovoj organizaciji."
 }
}
 
 
 BILKO-2006 — Cannot Modify Owner 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 403 
 
 
 Trigger 
 PUT /users/:id/role or DELETE /users/:id — target user is owner 
 
 
 
 {
 "error": {
 "code": "BILKO-2006",
 "message": "Nije moguće promijeniti ili ukloniti vlasnika organizacije."
 }
}
 
 
 BILKO-2007 — Cannot Remove Self 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 403 
 
 
 Trigger 
 DELETE /users/:id — user attempts to delete their own account 
 
 
 
 {
 "error": {
 "code": "BILKO-2007",
 "message": "Ne možete ukloniti vlastiti korisnički račun."
 }
}
 
 
 BILKO-2008 — Cannot Invite Existing Member 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 409 
 
 
 Trigger 
 POST /users/invite — email already belongs to a user in this organization 
 
 
 
 {
 "error": {
 "code": "BILKO-2008",
 "message": "Korisnik s ovim emailom je već član organizacije."
 }
}
 
 
 Module: Invoices (3xxx) 
 BILKO-3001 — Invoice Not Found 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 404 
 
 
 Trigger 
 GET/PUT/PATCH/DELETE /invoices/:id — ID not found in caller's organization 
 
 
 
 {
 "error": {
 "code": "BILKO-3001",
 "message": "Faktura nije pronađena."
 }
}
 
 
 BILKO-3002 — Customer Not Found 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 404 
 
 
 Trigger 
 POST /invoices — customerId does not exist in organization's contacts 
 
 
 
 {
 "error": {
 "code": "BILKO-3002",
 "message": "Klijent nije pronađen."
 }
}
 
 
 BILKO-3003 — Invoice Not in Draft Status 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 400 
 
 
 Trigger 
 PUT /invoices/:id — attempting to edit an invoice that is not in draft status 
 
 
 
 {
 "error": {
 "code": "BILKO-3003",
 "message": "Faktura se može mijenjati samo u statusu 'nacrt'.",
 "details": {
 "status": ["Trenutni status: sent. Samo nacrti se mogu uređivati."]
 }
 }
}
 
 
 BILKO-3004 — Invalid Invoice Status Transition 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 400 
 
 
 Trigger 
 PATCH /invoices/:id/status — action is not valid for current invoice status 
 
 
 
 Valid transitions: 
 
 draft → sent (action: send ) 
 sent or viewed → paid (action: mark-paid ) 
 Any non-cancelled → cancelled (action: cancel ) 
 
 {
 "error": {
 "code": "BILKO-3004",
 "message": "Nevažeća promjena statusa fakture.",
 "details": {
 "action": ["Akcija 'mark-paid' nije dozvoljena za status 'draft'."]
 }
 }
}
 
 
 BILKO-3005 — Customer Has No Email 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 400 
 
 
 Trigger 
 POST /invoices/:id/send — customer contact has no email field set 
 
 
 
 {
 "error": {
 "code": "BILKO-3005",
 "message": "Klijent nema email adresu. Dodajte email u kontakt podatke."
 }
}
 
 
 BILKO-3006 — Invoice Items Required 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 422 
 
 
 Trigger 
 POST /invoices — items array is empty 
 
 
 
 {
 "error": {
 "code": "BILKO-3006",
 "message": "Faktura mora imati najmanje jednu stavku.",
 "details": {
 "items": ["Polje items ne može biti prazno."]
 }
 }
}
 
 
 BILKO-3007 — Negative or Zero Amount 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 422 
 
 
 Trigger 
 POST /invoices or POST /invoices/:id/send — unitPrice or quantity is ≤ 0 
 
 
 
 {
 "error": {
 "code": "BILKO-3007",
 "message": "Iznosi moraju biti veći od nule.",
 "details": {
 "items[0].unitPrice": ["Cijena mora biti pozitivan broj."]
 }
 }
}
 
 
 BILKO-3008 — Invalid Tax Rate 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 422 
 
 
 Trigger 
 POST /invoices — taxRate is negative or exceeds 100 
 
 
 
 {
 "error": {
 "code": "BILKO-3008",
 "message": "Stopa poreza mora biti između 0 i 100.",
 "details": {
 "items[0].taxRate": ["Vrijednost mora biti između 0 i 100."]
 }
 }
}
 
 
 BILKO-3009 — Due Date Before Invoice Date 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 422 
 
 
 Trigger 
 POST /invoices — dueDate is before invoiceDate 
 
 
 
 {
 "error": {
 "code": "BILKO-3009",
 "message": "Datum dospijeća ne može biti prije datuma fakture.",
 "details": {
 "dueDate": ["Datum dospijeća mora biti isti ili kasniji od datuma fakture."]
 }
 }
}
 
 
 BILKO-3010 — Invoice PDF Not Available 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 404 
 
 
 Trigger 
 GET /invoices/:id/pdf — PDF has not yet been generated (invoice still in draft ) 
 
 
 
 {
 "error": {
 "code": "BILKO-3010",
 "message": "PDF faktura nije dostupan. Faktura mora biti poslana da bi se generirao PDF."
 }
}
 
 
 BILKO-3011 — Invoice Email Delivery Failed 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 500 
 
 
 Trigger 
 POST /invoices/:id/send — SendGrid API returned error 
 
 
 Retry 
 Yes — once, after 5 seconds 
 
 
 
 {
 "error": {
 "code": "BILKO-3011",
 "message": "Slanje emaila nije uspjelo. Pokušajte ponovo.",
 "requestId": "req_01H9X3K5P2M7N8Q4R6S9T0V1W2"
 }
}
 
 
 Module: Expenses (4xxx) 
 BILKO-4001 — Expense Not Found 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 404 
 
 
 Trigger 
 GET/PUT/PATCH/DELETE /expenses/:id — ID not in caller's organization 
 
 
 
 {
 "error": {
 "code": "BILKO-4001",
 "message": "Troškak nije pronađen."
 }
}
 
 
 BILKO-4002 — Expense Not in Pending Status 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 400 
 
 
 Trigger 
 PUT /expenses/:id or DELETE /expenses/:id — expense is not in pending status 
 
 
 
 {
 "error": {
 "code": "BILKO-4002",
 "message": "Troškak se može mijenjati ili brisati samo u statusu 'na čekanju'.",
 "details": {
 "status": ["Trenutni status: approved."]
 }
 }
}
 
 
 BILKO-4003 — Expense Already Processed 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 400 
 
 
 Trigger 
 PATCH /expenses/:id/approve — expense is already approved , paid , or rejected 
 
 
 
 {
 "error": {
 "code": "BILKO-4003",
 "message": "Troškak je već obrađen i ne može se odobriti ponovo.",
 "details": {
 "status": ["Trenutni status: approved."]
 }
 }
}
 
 
 BILKO-4004 — Vendor Not Found 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 404 
 
 
 Trigger 
 POST /expenses — vendorId not found in organization's contacts 
 
 
 
 {
 "error": {
 "code": "BILKO-4004",
 "message": "Dobavljač nije pronađen."
 }
}
 
 
 BILKO-4005 — Receipt File Too Large 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 413 
 
 
 Trigger 
 POST /expenses with receiptFile — file exceeds 10MB 
 
 
 
 {
 "error": {
 "code": "BILKO-4005",
 "message": "Fajl je prevelik. Maksimalna veličina je 10 MB."
 }
}
 
 
 BILKO-4006 — Invalid Receipt File Type 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 422 
 
 
 Trigger 
 POST /expenses with receiptFile — file is not PDF, PNG, or JPG 
 
 
 
 {
 "error": {
 "code": "BILKO-4006",
 "message": "Neispravni tip fajla. Dozvoljeni formati: PDF, PNG, JPG.",
 "details": {
 "receiptFile": ["Tip fajla 'docx' nije dozvoljen."]
 }
 }
}
 
 
 BILKO-4007 — Receipt Upload Failed 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 500 
 
 
 Trigger 
 Cloudflare R2 upload failed after ClamAV scan passed 
 
 
 Retry 
 Yes — exponential backoff 
 
 
 
 {
 "error": {
 "code": "BILKO-4007",
 "message": "Upload računa nije uspio. Pokušajte ponovo.",
 "requestId": "req_01H9X3K5P2M7N8Q4R6S9T0V1W2"
 }
}
 
 
 BILKO-4008 — File Rejected (Virus Detected) 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 422 
 
 
 Trigger 
 ClamAV scan detected malware in uploaded file 
 
 
 Retry 
 No 
 
 
 
 {
 "error": {
 "code": "BILKO-4008",
 "message": "Fajl nije prihvaćen zbog sigurnosnih razloga."
 }
}
 
 
 Module: Banking (5xxx) 
 BILKO-5001 — Bank Account Not Found 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 404 
 
 
 Trigger 
 GET/POST /bank-accounts/:id/* — ID not found in caller's organization 
 
 
 
 {
 "error": {
 "code": "BILKO-5001",
 "message": "Bankovni račun nije pronađen."
 }
}
 
 
 BILKO-5002 — GL Account Must Be Asset Type 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 422 
 
 
 Trigger 
 POST /bank-accounts — referenced accountId is not an Asset account type 
 
 
 
 {
 "error": {
 "code": "BILKO-5002",
 "message": "Konto za bankovni račun mora biti tipa 'Imovina'.",
 "details": {
 "accountId": ["Odabrani konto je tipa 'Rashodi'. Odaberite konto tipa 'Imovina'."]
 }
 }
}
 
 
 BILKO-5003 — GL Account Not Found 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 404 
 
 
 Trigger 
 POST /bank-accounts — accountId does not exist in organization 
 
 
 
 {
 "error": {
 "code": "BILKO-5003",
 "message": "Konto nije pronađen."
 }
}
 
 
 BILKO-5004 — Bank Transaction Not Found 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 404 
 
 
 Trigger 
 POST /bank-accounts/:id/reconcile — bankTransactionId not found 
 
 
 
 {
 "error": {
 "code": "BILKO-5004",
 "message": "Bankovna transakcija nije pronađena."
 }
}
 
 
 BILKO-5005 — Transaction Already Reconciled 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 400 
 
 
 Trigger 
 POST /bank-accounts/:id/reconcile — either transaction is already reconciled = true 
 
 
 
 {
 "error": {
 "code": "BILKO-5005",
 "message": "Transakcija je već usklađena."
 }
}
 
 
 BILKO-5006 — Invalid CSV Format 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 422 
 
 
 Trigger 
 POST /bank-accounts/:id/import — CSV missing required columns or malformed 
 
 
 
 {
 "error": {
 "code": "BILKO-5006",
 "message": "Nevažeći format CSV fajla.",
 "details": {
 "file": ["Obavezne kolone: Date, Description, Amount, Reference."]
 }
 }
}
 
 
 BILKO-5007 — CSV File Too Large 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 413 
 
 
 Trigger 
 POST /bank-accounts/:id/import — CSV file exceeds 5MB 
 
 
 
 {
 "error": {
 "code": "BILKO-5007",
 "message": "CSV fajl je prevelik. Maksimalna veličina je 5 MB."
 }
}
 
 
 BILKO-5008 — Invalid CSV Date Format 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 422 
 
 
 Trigger 
 POST /bank-accounts/:id/import — date column values not parseable as ISO 8601 
 
 
 
 {
 "error": {
 "code": "BILKO-5008",
 "message": "Nevažeći format datuma u CSV fajlu.",
 "details": {
 "file": ["Datumi moraju biti u formatu YYYY-MM-DD (npr. 2026-02-24)."]
 }
 }
}
 
 
 Module: Reports (6xxx) 
 BILKO-6001 — From Date Required 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 422 
 
 
 Trigger 
 GET /reports/profit-loss , /cash-flow , /vat — from query parameter missing 
 
 
 
 {
 "error": {
 "code": "BILKO-6001",
 "message": "Početni datum je obavezan.",
 "details": {
 "from": ["Parametar 'from' je obavezan."]
 }
 }
}
 
 
 BILKO-6002 — To Date Required 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 422 
 
 
 Trigger 
 GET /reports/profit-loss , /cash-flow , /vat — to query parameter missing 
 
 
 
 {
 "error": {
 "code": "BILKO-6002",
 "message": "Krajnji datum je obavezan.",
 "details": {
 "to": ["Parametar 'to' je obavezan."]
 }
 }
}
 
 
 BILKO-6003 — Invalid Date Range 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 422 
 
 
 Trigger 
 Any report endpoint — from date is after to date 
 
 
 
 {
 "error": {
 "code": "BILKO-6003",
 "message": "Nevažeći raspon datuma. Početni datum mora biti prije krajnjeg.",
 "details": {
 "from": ["Mora biti prije 'to' datuma."]
 }
 }
}
 
 
 BILKO-6004 — Trial Balance Not Balanced 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 500 
 
 
 Trigger 
 GET /reports/trial-balance — internal data integrity check failed (debit ≠ credit totals) 
 
 
 Retry 
 No — requires manual investigation 
 
 
 
 {
 "error": {
 "code": "BILKO-6004",
 "message": "Greška integriteta podataka: probni bilans nije uravnotežen. Kontaktirajte podršku.",
 "requestId": "req_01H9X3K5P2M7N8Q4R6S9T0V1W2"
 }
}
 
 
 Module: Contacts (7xxx) 
 BILKO-7001 — Contact Not Found 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 404 
 
 
 Trigger 
 GET/PUT/DELETE /contacts/:id — ID not found in caller's organization 
 
 
 
 {
 "error": {
 "code": "BILKO-7001",
 "message": "Kontakt nije pronađen."
 }
}
 
 
 BILKO-7002 — Contact Has Active Invoices 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 400 
 
 
 Trigger 
 DELETE /contacts/:id — contact has invoices with status other than cancelled 
 
 
 
 {
 "error": {
 "code": "BILKO-7002",
 "message": "Kontakt ne može biti deaktiviran jer ima aktivne fakture."
 }
}
 
 
 BILKO-7003 — Contact Has Active Expenses 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 400 
 
 
 Trigger 
 DELETE /contacts/:id — contact has expenses with status other than rejected 
 
 
 
 {
 "error": {
 "code": "BILKO-7003",
 "message": "Kontakt ne može biti deaktiviran jer ima aktivne troškove."
 }
}
 
 
 BILKO-7004 — Invalid ISO Country Code 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 422 
 
 
 Trigger 
 POST/PUT /contacts — country is not a valid ISO 3166-1 alpha-2 code 
 
 
 
 {
 "error": {
 "code": "BILKO-7004",
 "message": "Nevažeći kod države.",
 "details": {
 "country": ["Mora biti ISO 3166-1 alpha-2 kod (npr. 'RS', 'BA', 'HR')."]
 }
 }
}
 
 
 BILKO-7005 — Invalid Payment Terms 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 422 
 
 
 Trigger 
 POST/PUT /contacts — paymentTerms is negative or not an integer 
 
 
 
 {
 "error": {
 "code": "BILKO-7005",
 "message": "Rok plaćanja mora biti pozitivan cijeli broj (dani).",
 "details": {
 "paymentTerms": ["Mora biti pozitivni cijeli broj."]
 }
 }
}
 
 
 Module: Settings & Accounts (8xxx) 
 BILKO-8001 — Account Not Found 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 404 
 
 
 Trigger 
 PUT /accounts/:id — account UUID not found in caller's organization 
 
 
 
 {
 "error": {
 "code": "BILKO-8001",
 "message": "Konto nije pronađen."
 }
}
 
 
 BILKO-8002 — Account Code Already Exists 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 409 
 
 
 Trigger 
 POST /accounts — code is not unique within the organization 
 
 
 
 {
 "error": {
 "code": "BILKO-8002",
 "message": "Konto sa ovim kodom već postoji.",
 "details": {
 "code": ["Kod '1200' je već u upotrebi."]
 }
 }
}
 
 
 BILKO-8003 — Invalid Account Type 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 422 
 
 
 Trigger 
 POST /accounts — accountTypeId is not 1–5 
 
 
 
 {
 "error": {
 "code": "BILKO-8003",
 "message": "Nevažeći tip konta.",
 "details": {
 "accountTypeId": ["Mora biti između 1 (Imovina) i 5 (Rashodi)."]
 }
 }
}
 
 
 BILKO-8004 — Cannot Deactivate Account with Transactions 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 400 
 
 
 Trigger 
 PUT /accounts/:id — setting isActive = false on account that has transactions 
 
 
 
 {
 "error": {
 "code": "BILKO-8004",
 "message": "Konto se ne može deaktivirati jer ima postojeće transakcije."
 }
}
 
 
 BILKO-8005 — Parent Account Not Found 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 404 
 
 
 Trigger 
 POST /accounts — parentAccountId not found in organization 
 
 
 
 {
 "error": {
 "code": "BILKO-8005",
 "message": "Nadređeni konto nije pronađen."
 }
}
 
 
 BILKO-8006 — Invalid VAT Rate 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 422 
 
 
 Trigger 
 PUT /settings/tax-rates — any rate value is negative or exceeds 100 
 
 
 
 {
 "error": {
 "code": "BILKO-8006",
 "message": "Stopa PDV-a mora biti između 0 i 100.",
 "details": {
 "defaultVATRate": ["Vrijednost mora biti između 0 i 100."]
 }
 }
}
 
 
 General / Cross-cutting (9xxx) 
 BILKO-9001 — Insufficient Permissions 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 403 
 
 
 Trigger 
 Any endpoint — user's role not in allowedRoles for that endpoint 
 
 
 
 {
 "error": {
 "code": "BILKO-9001",
 "message": "Nemate dovoljna prava za ovu akciju.",
 "details": {
 "required": ["owner", "admin"],
 "current": ["accountant"]
 }
 }
}
 
 
 BILKO-9002 — Resource Not Found 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 404 
 
 
 Trigger 
 Generic fallback when a specific BILKO-Xxxx code doesn't apply 
 
 
 
 {
 "error": {
 "code": "BILKO-9002",
 "message": "Traženi resurs nije pronađen."
 }
}
 
 
 BILKO-9003 — Validation Failed 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 422 
 
 
 Trigger 
 Generic Zod schema validation failure when no specific BILKO-Xxxx code applies 
 
 
 
 {
 "error": {
 "code": "BILKO-9003",
 "message": "Validacija zahtjeva nije uspjela.",
 "details": {
 "fieldName": ["Opis greške validacije."]
 }
 }
}
 
 
 BILKO-9004 — Internal Server Error 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 500 
 
 
 Trigger 
 Unhandled exception; logged to Sentry with full stack trace 
 
 
 Retry 
 Yes — exponential backoff 
 
 
 
 {
 "error": {
 "code": "BILKO-9004",
 "message": "Došlo je do greške na serveru. Pokušajte ponovo.",
 "requestId": "req_01H9X3K5P2M7N8Q4R6S9T0V1W2"
 }
}
 
 
 BILKO-9005 — Rate Limit Exceeded 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 429 
 
 
 Trigger 
 General API rate limit exceeded (100 req/min for reads, 10–50 for writes) 
 
 
 Retry 
 Yes — after Retry-After header 
 
 
 
 {
 "error": {
 "code": "BILKO-9005",
 "message": "Previše zahtjeva. Usporite."
 }
}
 
 
 BILKO-9006 — Database Error 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 500 
 
 
 Trigger 
 Prisma throws unexpected DB error (connection lost, constraint violation from race condition) 
 
 
 Retry 
 Yes — exponential backoff 
 
 
 
 {
 "error": {
 "code": "BILKO-9006",
 "message": "Greška baze podataka. Pokušajte ponovo.",
 "requestId": "req_01H9X3K5P2M7N8Q4R6S9T0V1W2"
 }
}
 
 
 BILKO-9007 — External Service Unavailable 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 503 
 
 
 Trigger 
 SendGrid, Cloudflare R2, or ECB API is unreachable after internal retries exhausted 
 
 
 Retry 
 Yes — exponential backoff; 503 responses include Retry-After 
 
 
 
 {
 "error": {
 "code": "BILKO-9007",
 "message": "Vanjska usluga trenutno nije dostupna. Pokušajte ponovo za nekoliko minuta.",
 "requestId": "req_01H9X3K5P2M7N8Q4R6S9T0V1W2"
 }
}
 
 
 BILKO-9008 — Invalid Pagination Parameters 
 
 
 
 Field 
 Value 
 
 
 
 
 HTTP 
 400 
 
 
 Trigger 
 Any list endpoint — page < 1 , perPage > 100 , or non-integer values 
 
 
 
 {
 "error": {
 "code": "BILKO-9008",
 "message": "Nevažeći parametri paginacije.",
 "details": {
 "perPage": ["Maksimalna vrijednost je 100."],
 "page": ["Mora biti pozitivan cijeli broj."]
 }
 }
}
 
 
 i18n Error Messages 
 All error message fields are returned in the organization's configured language ( sr , bs , hr , en ). Codes and details keys are always in English to enable programmatic handling. 
 Message localization table (selected codes): 
 
 
 
 Code 
 SR (Serbian) 
 BS (Bosnian) 
 HR (Croatian) 
 EN (English) 
 
 
 
 
 BILKO-1001 
 Pogrešan email ili lozinka. 
 Pogrešan email ili lozinka. 
 Pogrešan email ili lozinka. 
 Invalid email or password. 
 
 
 BILKO-1003 
 Sesija je istekla. Osvježite token. 
 Sesija je istekla. Osvježite token. 
 Sesija je istekla. Osvježite token. 
 Session expired. Please refresh your token. 
 
 
 BILKO-1005 
 Autentifikacija je obavezna. 
 Autentifikacija je obavezna. 
 Autentifikacija je obavezna. 
 Authentication is required. 
 
 
 BILKO-1007 
 Previše pokušaja prijave. Pokušajte za 15 min. 
 Previše pokušaja prijave. Pokušajte za 15 min. 
 Previše pokušaja prijave. Pokušajte za 15 min. 
 Too many login attempts. Try again in 15 minutes. 
 
 
 BILKO-1008 
 Email adresa je već registrirana. 
 Email adresa je već registrirana. 
 Email adresa je već registrirana. 
 Email address is already registered. 
 
 
 BILKO-3001 
 Faktura nije pronađena. 
 Faktura nije pronađena. 
 Faktura nije pronađena. 
 Invoice not found. 
 
 
 BILKO-4001 
 Troškak nije pronađen. 
 Troškak nije pronađen. 
 Trošak nije pronađen. 
 Expense not found. 
 
 
 BILKO-7001 
 Kontakt nije pronađen. 
 Kontakt nije pronađen. 
 Kontakt nije pronađen. 
 Contact not found. 
 
 
 BILKO-9001 
 Nemate dovoljna prava za ovu akciju. 
 Nemate dovoljna prava za ovu akciju. 
 Nemate dovoljna prava za ovu akciju. 
 You do not have permission to perform this action. 
 
 
 BILKO-9003 
 Validacija zahtjeva nije uspjela. 
 Validacija zahtjeva nije uspjela. 
 Provjera zahtjeva nije uspjela. 
 Request validation failed. 
 
 
 BILKO-9004 
 Došlo je do greške na serveru. 
 Došlo je do greške na serveru. 
 Došlo je do pogreške na poslužitelju. 
 An internal server error occurred. 
 
 
 BILKO-9005 
 Previše zahtjeva. Usporite. 
 Previše zahtjeva. Usporite. 
 Previše zahtjeva. Usporite. 
 Too many requests. Please slow down. 
 
 
 
 Implementation: Error messages are stored in /src/lib/i18n/errors/ with one file per language ( sr.json , bs.json , hr.json , en.json ). The message is selected using the organization's language field from the JWT orgId lookup. 
 // src/lib/i18n/errors/en.json (excerpt)
{
 "BILKO-1001": "Invalid email or password.",
 "BILKO-1003": "Session expired. Please refresh your token.",
 "BILKO-9001": "You do not have permission to perform this action."
}
 
 // src/lib/error-formatter.ts
function formatError(code: string, orgLanguage: string, details?: Record<string, string[]>) {
 const messages = require(`./i18n/errors/${orgLanguage}.json`)
 return {
 error: {
 code,
 message: messages[code] ?? messages['BILKO-9004'],
 ...(details && { details }),
 }
 }
}
 
 
 Quick Reference — All Error Codes 
 
 
 
 Code 
 HTTP 
 Module 
 Short Description 
 
 
 
 
 BILKO-1001 
 401 
 Auth 
 Invalid credentials 
 
 
 BILKO-1002 
 403 
 Auth 
 Account disabled 
 
 
 BILKO-1003 
 401 
 Auth 
 Access token expired 
 
 
 BILKO-1004 
 401 
 Auth 
 Invalid token 
 
 
 BILKO-1005 
 401 
 Auth 
 No token provided 
 
 
 BILKO-1006 
 401 
 Auth 
 Refresh token invalid/expired 
 
 
 BILKO-1007 
 429 
 Auth 
 Auth rate limit exceeded 
 
 
 BILKO-1008 
 409 
 Auth 
 Email already registered 
 
 
 BILKO-1009 
 422 
 Auth 
 Weak password 
 
 
 BILKO-1010 
 403 
 Auth 
 2FA required 
 
 
 BILKO-1011 
 401 
 Auth 
 Invalid 2FA code 
 
 
 BILKO-1012 
 401 
 Auth 
 Invalid invite token 
 
 
 BILKO-2001 
 404 
 Org 
 Organization not found 
 
 
 BILKO-2002 
 422 
 Org 
 Invalid currency code 
 
 
 BILKO-2003 
 422 
 Org 
 Invalid language code 
 
 
 BILKO-2004 
 400 
 Org 
 Cannot change base currency 
 
 
 BILKO-2005 
 404 
 Org 
 User not found in org 
 
 
 BILKO-2006 
 403 
 Org 
 Cannot modify owner 
 
 
 BILKO-2007 
 403 
 Org 
 Cannot remove self 
 
 
 BILKO-2008 
 409 
 Org 
 User already a member 
 
 
 BILKO-3001 
 404 
 Invoices 
 Invoice not found 
 
 
 BILKO-3002 
 404 
 Invoices 
 Customer not found 
 
 
 BILKO-3003 
 400 
 Invoices 
 Invoice not in draft 
 
 
 BILKO-3004 
 400 
 Invoices 
 Invalid status transition 
 
 
 BILKO-3005 
 400 
 Invoices 
 Customer has no email 
 
 
 BILKO-3006 
 422 
 Invoices 
 Items array empty 
 
 
 BILKO-3007 
 422 
 Invoices 
 Negative/zero amount 
 
 
 BILKO-3008 
 422 
 Invoices 
 Invalid tax rate 
 
 
 BILKO-3009 
 422 
 Invoices 
 Due date before invoice date 
 
 
 BILKO-3010 
 404 
 Invoices 
 PDF not available 
 
 
 BILKO-3011 
 500 
 Invoices 
 Email delivery failed 
 
 
 BILKO-4001 
 404 
 Expenses 
 Expense not found 
 
 
 BILKO-4002 
 400 
 Expenses 
 Expense not pending 
 
 
 BILKO-4003 
 400 
 Expenses 
 Expense already processed 
 
 
 BILKO-4004 
 404 
 Expenses 
 Vendor not found 
 
 
 BILKO-4005 
 413 
 Expenses 
 Receipt file too large 
 
 
 BILKO-4006 
 422 
 Expenses 
 Invalid file type 
 
 
 BILKO-4007 
 500 
 Expenses 
 Upload failed 
 
 
 BILKO-4008 
 422 
 Expenses 
 Virus detected in file 
 
 
 BILKO-5001 
 404 
 Banking 
 Bank account not found 
 
 
 BILKO-5002 
 422 
 Banking 
 GL account must be Asset type 
 
 
 BILKO-5003 
 404 
 Banking 
 GL account not found 
 
 
 BILKO-5004 
 404 
 Banking 
 Bank transaction not found 
 
 
 BILKO-5005 
 400 
 Banking 
 Transaction already reconciled 
 
 
 BILKO-5006 
 422 
 Banking 
 Invalid CSV format 
 
 
 BILKO-5007 
 413 
 Banking 
 CSV file too large 
 
 
 BILKO-5008 
 422 
 Banking 
 Invalid CSV date format 
 
 
 BILKO-6001 
 422 
 Reports 
 From date required 
 
 
 BILKO-6002 
 422 
 Reports 
 To date required 
 
 
 BILKO-6003 
 422 
 Reports 
 Invalid date range 
 
 
 BILKO-6004 
 500 
 Reports 
 Trial balance not balanced 
 
 
 BILKO-7001 
 404 
 Contacts 
 Contact not found 
 
 
 BILKO-7002 
 400 
 Contacts 
 Contact has active invoices 
 
 
 BILKO-7003 
 400 
 Contacts 
 Contact has active expenses 
 
 
 BILKO-7004 
 422 
 Contacts 
 Invalid country code 
 
 
 BILKO-7005 
 422 
 Contacts 
 Invalid payment terms 
 
 
 BILKO-8001 
 404 
 Accounts 
 Account not found 
 
 
 BILKO-8002 
 409 
 Accounts 
 Account code already exists 
 
 
 BILKO-8003 
 422 
 Accounts 
 Invalid account type 
 
 
 BILKO-8004 
 400 
 Accounts 
 Cannot deactivate account with transactions 
 
 
 BILKO-8005 
 404 
 Accounts 
 Parent account not found 
 
 
 BILKO-8006 
 422 
 Settings 
 Invalid VAT rate 
 
 
 BILKO-9001 
 403 
 General 
 Insufficient permissions 
 
 
 BILKO-9002 
 404 
 General 
 Resource not found 
 
 
 BILKO-9003 
 422 
 General 
 Validation failed 
 
 
 BILKO-9004 
 500 
 General 
 Internal server error 
 
 
 BILKO-9005 
 429 
 General 
 Rate limit exceeded 
 
 
 BILKO-9006 
 500 
 General 
 Database error 
 
 
 BILKO-9007 
 503 
 General 
 External service unavailable 
 
 
 BILKO-9008 
 400 
 General 
 Invalid pagination parameters 
 
 
 
 
 End of Error Codes Catalog