Foutreferentie

Alle qr3.app API-fouten volgen RFC 7807 Problem Details met Content-Type: application/problem+json.

{
  "type": "https://docs.qr3.app/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "QR code qr_xxx not found"
}

`errors/validation`

HTTP 422 Unprocessable Entity

De invoergegevens zijn niet door de schemavalidatie gekomen. De response bevat een errors-array met details per veld.

{
  "type": "https://docs.qr3.app/errors/validation",
  "title": "Validation Error",
  "status": 422,
  "detail": "Request body validation failed",
  "errors": [
    { "field": "url", "message": "Invalid URL format" }
  ]
}

Oorzaken: Ontbrekende verplichte velden, onjuiste datatypen, waarden buiten het toegestane bereik, ongeldige URL-indeling.

`errors/bad-request`

HTTP 400 Bad Request

De body is geen geldige JSON, hoewel Content-Type: application/json is ingesteld (bijv. een komma na het laatste element, een afgekapte of een lege body).

`errors/authentication`

HTTP 401 Unauthorized

De API-key ontbreekt, is onjuist geformatteerd, verlopen of ingetrokken.

Oplossing: Controleer of de Authorization: Bearer qr3_sk_... header aanwezig is en of de key actief is.

`errors/unauthorized`

HTTP 401 Unauthorized

Een inkomende webhook (POST /v1/webhooks/clerk, POST /v1/webhooks/eu-registry) is aangeroepen zonder geldige handtekening of geheim. Een ontbrekende of ongeldige API-key antwoordt in plaats daarvan met errors/authentication.

`errors/authorization`

HTTP 403 Forbidden

De API-key is geldig, maar heeft niet de vereiste scope of de nodige machtigingen.

`errors/forbidden`

HTTP 403 Forbidden

De bron bestaat, maar behoort tot een andere workspace of een andere organisatie.

`errors/document-immutable`

HTTP 403 Forbidden

Een DPP-document dat met is_immutable is geüpload, kan niet worden verwijderd.

`errors/not-found`

HTTP 404 Not Found

De opgevraagde bron bestaat niet of is verwijderd.

`errors/conflict`

HTTP 409 Conflict

Er bestaat al een bron met dezelfde unieke identificatie (bijv. dubbele slug of Idempotency-Key-botsing).

`errors/subscription-exists`

HTTP 409 Conflict

POST /v1/billing/checkout is aangeroepen hoewel de organisatie al een abonnement heeft. Wijzig in plaats daarvan het plan in het facturatieportaal.

`errors/rate-limited`

HTTP 429 Too Many Requests

De rate-limit per minuut van de API-key is overschreden. De response bevat de headers Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining en X-RateLimit-Reset.

`errors/rate-limit`

HTTP 429 Too Many Requests

Een bronspecifieke rate-limit is overschreden (bijv. 200 QR-codes per dag per workspace).

`errors/plan-limit`

HTTP 422 Unprocessable Entity

Je huidige plan staat deze actie niet toe (bijv. quotum voor DPP’s of dynamische codes verbruikt, batch te groot, te veel workspaces of teamleden). Upgrade vereist.

`errors/invalid-file-type`

HTTP 400 Bad Request

Het geüploade bestand is van een type dat het eindpunt niet accepteert, of de inhoud komt niet overeen met de opgegeven Content-Type.

`errors/file-too-large`

HTTP 413 Payload Too Large

Het geüploade bestand overschrijdt de groottelimiet van het plan of van het eindpunt.

`errors/storage-limit-exceeded`

HTTP 422 Unprocessable Entity

De upload zou de totale opslagruimte van de workspace of van het DPP overschrijden.

`errors/not-configured`

HTTP 503 Service Unavailable

Een vereiste service of configuratie ontbreekt (bijv. Stripe niet geconfigureerd, Web Risk API-key niet ingesteld).

`errors/unsafe-url`

HTTP 422 Unprocessable Entity

De URL is geweigerd omdat deze door Google Web Risk als onveilig is geclassificeerd (malware, phishing, social engineering).

`errors/url-flagged`

HTTP 422 Unprocessable Entity

Gereserveerd voor URL’s die achteraf bij periodieke herscans als onveilig zijn geclassificeerd.

`errors/already-submitted`

HTTP 409 Conflict

Dubbele indiening — er is bijvoorbeeld deze maand al een NPS-score voor deze workspace ingediend.

`errors/unprocessable-entity`

HTTP 422 Unprocessable Entity

Een admin-actie is niet toegestaan (bijv. het impersoneren van een andere superadmin). Alleen de superadmin-eindpunten retourneren dit type.

`errors/request-error`

HTTP 4xx Client Error

Fallback voor clientfouten zonder specifieker type; de status staat in de respons. De API heeft momenteel geen bekende paden die dit retourneren.

`errors/internal`

HTTP 500 Internal Server Error

Een onverwachte fout op de server. Probeer het verzoek opnieuw. Bij aanhoudende problemen: [email protected].