Αναφορά Σφαλμάτων

Όλα τα σφάλματα του qr3.app API ακολουθούν το RFC 7807 Problem Details με 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

Τα δεδομένα εισόδου απέτυχαν στην επικύρωση σχήματος (schema validation). Η απάντηση (Response) περιέχει έναν πίνακα errors με λεπτομέρειες ανά πεδίο.

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

Αιτίες: Ελλείποντα υποχρεωτικά πεδία, εσφαλμένοι τύποι δεδομένων, τιμές εκτός του επιτρεπόμενου εύρους, μη έγκυρη μορφή URL.

`errors/bad-request`

HTTP 400 Bad Request

Το σώμα (body) δεν είναι έγκυρο JSON παρόλο που έχει οριστεί το Content-Type: application/json (π.χ. ένα τελικό κόμμα, ένα ημιτελές ή ένα κενό σώμα).

`errors/authentication`

HTTP 401 Unauthorized

Το API-Key λείπει, έχει εσφαλμένη μορφή, έχει λήξει ή έχει ανακληθεί.

Επίλυση: Ελέγξτε αν υπάρχει η κεφαλίδα Authorization: Bearer qr3_sk_... και αν το κλειδί είναι ενεργό.

`errors/unauthorized`

HTTP 401 Unauthorized

Ένα εισερχόμενο webhook (POST /v1/webhooks/clerk, POST /v1/webhooks/eu-registry) κλήθηκε χωρίς έγκυρη υπογραφή ή μυστικό κλειδί. Ένα ελλείπον ή μη έγκυρο API key απαντά αντ’ αυτού με errors/authentication.

`errors/authorization`

HTTP 403 Forbidden

Το API-Key είναι έγκυρο, αλλά δεν διαθέτει το απαιτούμενο scope ή την απαραίτητη εξουσιοδότηση.

`errors/forbidden`

HTTP 403 Forbidden

Ο πόρος υπάρχει, αλλά ανήκει σε διαφορετικό Workspace ή σε άλλον οργανισμό.

`errors/document-immutable`

HTTP 403 Forbidden

Ένα έγγραφο DPP που μεταφορτώθηκε με την παράμετρο is_immutable δεν μπορεί να διαγραφεί.

`errors/not-found`

HTTP 404 Not Found

Ο πόρος που ζητήθηκε δεν υπάρχει ή έχει διαγραφεί.

`errors/conflict`

HTTP 409 Conflict

Ένας πόρος με το ίδιο μοναδικό αναγνωριστικό υπάρχει ήδη (π.χ. διπλότυπο slug ή σύγκρουση Idempotency-Key).

`errors/subscription-exists`

HTTP 409 Conflict

Το POST /v1/billing/checkout κλήθηκε παρόλο που ο οργανισμός έχει ήδη μια συνδρομή. Αλλάξτε το πρόγραμμα στο portal χρέωσης αντ’ αυτού.

`errors/rate-limited`

HTTP 429 Too Many Requests

Το όριο ρυθμού (rate limit) ανά λεπτό του API-Key έχει ξεπεραστεί. Η απάντηση περιέχει τις κεφαλίδες Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining και X-RateLimit-Reset.

`errors/rate-limit`

HTTP 429 Too Many Requests

Ένα συγκεκριμένο ανά πόρο όριο ρυθμού (rate limit) έχει ξεπεραστεί (π.χ. 200 QR-Codes ανά ημέρα ανά Workspace).

`errors/plan-limit`

HTTP 422 Unprocessable Entity

Το τρέχον πρόγραμμά σας δεν επιτρέπει αυτή την ενέργεια (π.χ. εξάντληση ποσόστωσης DPP ή δυναμικών κωδίκων, πολύ μεγάλη παρτίδα, πάρα πολλά Workspaces ή μέλη ομάδας). Απαιτείται αναβάθμιση.

`errors/invalid-file-type`

HTTP 400 Bad Request

Το αρχείο που μεταφορτώθηκε έχει έναν τύπο που δεν αποδέχεται το endpoint, ή το περιεχόμενό του δεν αντιστοιχεί στο δηλωμένο Content-Type.

`errors/file-too-large`

HTTP 413 Payload Too Large

Το αρχείο που μεταφορτώθηκε υπερβαίνει το όριο μεγέθους του προγράμματος ή του endpoint.

`errors/storage-limit-exceeded`

HTTP 422 Unprocessable Entity

Η μεταφόρτωση θα υπερέβαινε τον συνολικό αποθηκευτικό χώρο του Workspace ή του DPP.

`errors/not-configured`

HTTP 503 Service Unavailable

Μια απαιτούμενη υπηρεσία ή ρύθμιση παραμέτρων λείπει (π.χ. το Stripe δεν έχει ρυθμιστεί, το Web Risk API-Key δεν έχει οριστεί).

`errors/unsafe-url`

HTTP 422 Unprocessable Entity

Το URL απορρίφθηκε επειδή κατηγοριοποιήθηκε ως μη ασφαλές από το Google Web Risk (Malware, Phishing, Social Engineering).

`errors/url-flagged`

HTTP 422 Unprocessable Entity

Δεσμευμένο για URL που χαρακτηρίστηκαν εκ των υστέρων ως μη ασφαλή κατά την περιοδική επανασάρωση (re-scanning).

`errors/already-submitted`

HTTP 409 Conflict

Διπλότυπη υποβολή — π.χ. έχει ήδη υποβληθεί βαθμολογία NPS για αυτό το Workspace αυτόν τον μήνα.

`errors/unprocessable-entity`

HTTP 422 Unprocessable Entity

Μια ενέργεια διαχειριστή δεν επιτρέπεται (π.χ. η προσομοίωση/impersonation ενός άλλου superadmin). Μόνο τα endpoints του superadmin επιστρέφουν αυτόν τον τύπο.

`errors/request-error`

HTTP 4xx Client Error

Τύπος ασφαλείας (fallback) για σφάλματα πελάτη χωρίς πιο συγκεκριμένο τύπο· η κατάσταση βρίσκεται στην απάντηση. Το API δεν έχει αυτή τη στιγμή κάποια γνωστή διαδρομή που να τον επιστρέφει.

`errors/internal`

HTTP 500 Internal Server Error

Παρουσιάστηκε ένα μη αναμενόμενο σφάλμα στον διακομιστή. Παρακαλούμε επαναλάβετε το αίτημα. Εάν το πρόβλημα επιμένει: [email protected].