Virhekoodireferenssi

Tämä sivu dokumentoi kaikki Kirjapro API:n palauttamat virhekoodit.

Vastausrakenne

Onnistunut vastaus

{
  "success": true,
  "data": { ... }
}

Virheellinen vastaus

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Ihmisluettava virhekuvaus",
    "details": { ... }
  }
}

HTTP-statuskoodit

Koodi	Merkitys	Toimenpide
200	Onnistui	-
201	Luotu	Resurssi luotu onnistuneesti
400	Virheellinen pyyntö	Tarkista pyynnön rakenne
401	Ei autentikoitu	Uusi access token
403	Ei oikeuksia	Tarkista käyttöoikeudet
404	Ei löydy	Tarkista resurssin ID
422	Validointivirhe	Korjaa data ja yritä uudelleen
429	Liikaa pyyntöjä	Odota ja yritä uudelleen
500	Palvelinvirhe	Ota yhteyttä tukeen

Autentikointivirheet

Koodi	Viesti	Ratkaisu
`AUTH_TOKEN_EXPIRED`	Token vanhentunut	Hae uusi token `supabase.auth.refreshSession()`
`AUTH_TOKEN_INVALID`	Virheellinen token	Kirjaudu uudelleen
`AUTH_TOKEN_MISSING`	Token puuttuu	Lisää Authorization-header
`AUTH_INSUFFICIENT_PERMISSIONS`	Riittämättömät oikeudet	Tarkista käyttäjärooli

Validointivirheet

Koodi	Viesti	Ratkaisu
`VALIDATION_BUSINESS_ID`	Virheellinen Y-tunnus	Muoto: 1234567-8
`VALIDATION_IBAN`	Virheellinen IBAN	Suomi: FI + 16 numeroa
`VALIDATION_REFERENCE`	Virheellinen viitenumero	4-20 numeroa, tarkiste oikein
`VALIDATION_EMAIL`	Virheellinen sähköposti	Tarkista muoto
`VALIDATION_REQUIRED`	Pakollinen kenttä puuttuu	Katso `details.field`
`VALIDATION_FORMAT`	Väärä muoto	Katso `details.expected`

Liiketoimintavirheet

Koodi	Viesti	Ratkaisu
`FISCAL_YEAR_LOCKED`	Tilikausi on lukittu	Avaa tilikausi ennen muokkausta
`FISCAL_YEAR_NOT_FOUND`	Tilikautta ei löydy	Luo tilikausi ensin
`BALANCE_MISMATCH`	Kirjaus ei tasapainota	Debet = Kredit
`INVOICE_ALREADY_SENT`	Lasku jo lähetetty	Ei voi lähettää uudelleen
`INVOICE_NOT_READY`	Lasku ei valmis	Täytä pakolliset kentät
`CUSTOMER_NOT_FOUND`	Asiakasta ei löydy	Tarkista asiakas-ID
`ACCOUNT_NOT_FOUND`	Tiliä ei löydy	Tarkista tilinumero

Integraatiovirheet

APIX (verkkolaskut)

Koodi	Viesti	Ratkaisu
`APIX_AUTH_FAILED`	Autentikointi epäonnistui	Tarkista API-avaimet asetuksista
`APIX_RECIPIENT_NOT_FOUND`	Vastaanottajaa ei löydy	Tarkista OVT-tunnus ja operaattori
`APIX_INVALID_INVOICE`	Virheellinen lasku	Validoi Finvoice XML
`APIX_RATE_LIMITED`	Liikaa pyyntöjä	Odota hetki

Stripe (tilaukset)

Koodi	Viesti	Ratkaisu
`STRIPE_CUSTOMER_NOT_FOUND`	Asiakasta ei löydy	Käyttäjän tulee ensin tehdä tilaus
`STRIPE_SUBSCRIPTION_INACTIVE`	Tilaus ei aktiivinen	Tarkista tilauksen tila
`STRIPE_WEBHOOK_INVALID`	Virheellinen webhook	Tarkista allekirjoitus
`INVALID_PRICE_ID`	Virheellinen hinta-ID	Tarkista Stripe-konfiguraatio
`PORTAL_SESSION_FAILED`	Portaali-istunto epäonnistui	Kokeile uudelleen

Korttimaksulinkit

Koodi	Viesti	Ratkaisu
`INVOICE_NOT_FOUND`	Laskua ei löydy	Tarkista laskun ID
`INVOICE_ALREADY_PAID`	Lasku on jo maksettu	Maksulinkkiä ei voi luoda
`INVOICE_CANCELLED`	Lasku on peruutettu	Maksulinkkiä ei voi luoda
`AMOUNT_TOO_LOW`	Summa alle 0,50 EUR	Nosta summa vähintään 0,50 euroon
`AMOUNT_TOO_HIGH`	Summa yli 999 999,99 EUR	Laske summaa
`FEATURE_NOT_AVAILABLE`	Paketti ei riitä	Päivitä Yrittäjä-pakettiin

Rate Limiting

Kun ylität pyyntörajan:

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Liian monta pyyntöä",
    "details": {
      "retryAfter": 60
    }
  }
}

Retry-strategia

Suositeltu käsittelytapa:

async function apiCall(fn: () => Promise<Response>, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fn();

    if (response.ok) return response.json();

    // Älä yritä uudelleen client-virheillä
    if (response.status >= 400 && response.status < 500 && response.status !== 429) {
      throw new Error(`Client error: ${response.status}`);
    }

    // Rate limit - odota
    if (response.status === 429) {
      const data = await response.json();
      const wait = data.error?.details?.retryAfter || 60;
      await new Promise(r => setTimeout(r, wait * 1000));
      continue;
    }

    // Server-virhe - exponential backoff
    await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));
  }

  throw new Error('Max retries exceeded');
}

Virheiden lokitus

Suosittelemme lokittamaan virheet debuggausta varten:

if (!result.success) {
  console.error('API Error:', {
    code: result.error.code,
    message: result.error.message,
    details: result.error.details,
    endpoint: '/functions/v1/...',
    timestamp: new Date().toISOString()
  });
}

Tuki

Jos kohtaat odottamattoman virheen, ota yhteyttä:

Sähköposti: tuki@kirjapro.fi
Liitä mukaan: virhekoodi, aikaleima, pyynnön tiedot