> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getqr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Virheet

> GetQR API:n palauttama virhemuoto ja virhekoodit.

> [!NOTE]
>
> GetQR API on beetavaiheessa, ja se on käytettävissä valituissa työtiloissa. Yksityiskohdat voivat muuttua ennen yleistä julkaisua.

GetQR API käyttää tavallisia HTTP-tilakoodeja. Onnistuneet pyynnöt palauttavat `2xx`. Epäonnistuneet pyynnöt palauttavat `4xx` tai `5xx` sekä JSON-rungon, joka kertoo, mikä meni vikaan.

## Virhemuoto

Jokaisella virheellä on sama rakenne: pysyvä koodi, ihmisen luettava viesti ja linkki kyseisen koodin kuvaukseen.

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized: Invalid API key.",
    "doc_url": "https://getqr.com/account/api-docs#error-unauthorized"
  }
}
```

**error.code** `string` *required*

Pysyvä, koneluettava virhekoodi. Käytä koodissasi tätä viestin sijaan. Katso [Virhekoodit](#virhekoodit).

**error.message** `string` *required*

Ihmisen luettava kuvaus ongelmasta. Sanamuoto voi muuttua.

**error.doc\_url** `string` *required*

Linkki virhekoodin kuvaukseen GetQR-tilisi API-dokumentaatiossa.

## Virhekoodit

| Koodi | HTTP-tila | Milloin se ilmenee |
| - | - | - |
| `bad_request` | 400 | Pyyntö on virheellisesti muodostettu: runko ei ole kelvollista JSONia, `Authorization`-otsakkeesta puuttuu `Bearer `-etuliite tai toiminto ei ole sallittu resurssin nykyisessä tilassa (esimerkiksi valmiin joukkoluonnin peruuttaminen). |
| `unauthorized` | 401 | API-avain puuttuu tai on virheellinen, esimerkiksi koska se on luotu uudelleen. |
| `forbidden` | 403 | Työtilan omistajan tilaus ei ole aktiivinen, tai roolisi työtilassa ei salli tätä toimintoa. |
| `exceeded_limit` | 403 | Olet saavuttanut tilauksesi rajan. Single QR -tilauksessa: QR-koodin luominen tai monistaminen, kun työtilassa on jo yksi, tai joukkoluonnin aloittaminen. |
| `not_found` | 404 | Resurssia ei ole olemassa tai se ei ole työtilassasi, päätepistettä ei ole olemassa tai API ei ole käytössä työtilassasi. |
| `method_not_allowed` | 405 | Päätepiste on olemassa, mutta se ei hyväksy tätä HTTP-metodia. `Allow`-otsake luettelee sen hyväksymät metodit. |
| `conflict` | 409 | Pyyntö on ristiriidassa olemassa olevien tietojen kanssa: lyhytlinkin slug on varattu, pyyntö samalla `Idempotency-Key`-arvolla on yhä kesken, ajastus menee päällekkäin olemassa olevan kanssa tai joukkoluonnin arkisto ei ole vielä valmis. |
| `invite_pending` | 409 | Sinut on kutsuttu työtilaan, mutta et ole vielä liittynyt. API-avaimella tehdyt pyynnöt eivät palauta tätä: avaimen työtila on aina sellainen, johon kuulut. |
| `invite_expired` | 410 | Kutsusi työtilaan on vanhentunut. API-avaimella tehdyt pyynnöt eivät palauta tätä samasta syystä. |
| `unprocessable_entity` | 422 | Runko tai kyselyparametrit eivät läpäisseet validointia. Viesti nimeää kentän ja kertoo, mikä siinä on vialla. Katso [Validointivirheet](#validointivirheet). |
| `rate_limit_exceeded` | 429 | API-avain on käyttänyt nykyisen aikaikkunan pyyntönsä loppuun. Katso [Käyttörajoitukset](https://docs.getqr.com/fi/api/rate-limits.md). |
| `internal_server_error` | 500 | Jotain meni vikaan meidän päässämme. Yritä myöhemmin uudelleen ja ota yhteyttä tukeen, jos ongelma jatkuu. |

## Validointivirheet

Kun runko tai kyselyparametrit eivät läpäise validointia, API vastaa `422`. Viesti kuvaa ensimmäisen virheellisen kentän muodossa `<issue>: <field>: <details>`:

```json theme={null}
{
  "error": {
    "code": "unprocessable_entity",
    "message": "too_big: pageSize: Max page size is 100.",
    "doc_url": "https://getqr.com/account/api-docs#error-unprocessable_entity"
  }
}
```

Sisäkkäiset kentät käyttävät pistenotaatiota, esimerkiksi `link.url`.

## Virheiden käsittely

* Haaraudu kentän `error.code` mukaan, älä kentän `error.message` mukaan.
* Älä yritä `4xx`-virheitä uudelleen muuttamattomina: korjaa ensin pyyntö. Poikkeuksia ovat yhä keskeneräisen pyynnön `409` sekä `429`.
* Kun saat `429`, odota `Retry-After`-otsakkeen ilmoittama määrä sekunteja. Katso [Käyttörajoitukset](https://docs.getqr.com/fi/api/rate-limits.md#kun-raja-ylittyy).
* Yritä `5xx`-virheitä uudelleen eksponentiaalisesti kasvavin viivein.

## Yleisiä ongelmia

> [accordion] Jokainen pyyntö palauttaa 404 "This endpoint is not available."
>
> API on beetavaiheessa, eikä sitä ole vielä otettu käyttöön työtilassasi.

> [accordion] 404 "This endpoint does not exist."
>
> Polku on väärä. Vertaa sitä päätepistesivuihin ja tarkista, että se alkaa merkkijonolla `/api/v1/`.

> [accordion] 403 "Access denied: This account does not have an active subscription."
>
> Työtilan omistajan tilaus on päättynyt. API-avain toimii taas heti, kun omistaja tilaa uudelleen.

> [accordion] 403 "API access is not available for this role."
>
> Roolisi työtilassa on katselija. Vain työtilan omistaja ja muokkaajat voivat käyttää APIa.

## Mitä seuraavaksi

> [card] [Käyttörajoitukset](https://docs.getqr.com/fi/api/rate-limits.md)

> [card] [Todennus](https://docs.getqr.com/fi/api/authentication.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.