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

Όλα τα σφάλματα του 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/authentication`

HTTP 401 Unauthorized

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

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

`errors/authorization`

HTTP 403 Forbidden

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

`errors/forbidden`

HTTP 403 Forbidden

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

`errors/not-found`

HTTP 404 Not Found

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

`errors/conflict`

HTTP 409 Conflict

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

`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 429 Too Many Requests

Το τρέχον πρόγραμμα (plan) δεν επιτρέπει αυτή την ενέργεια (π.χ. πάρα πολλά Workspaces). Απαιτείται αναβάθμιση.

`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/internal`

HTTP 500 Internal Server Error

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