Κώδικες σφάλματος API και βέλτιστες πρακτικές

1) Γιατί να τυποποιηθούν τα σφάλματα

Προβλεψιμότητα για τους πελάτες: μια ενιαία μορφή και συμπεριφορά των ρετρα.
Επιτάχυνση αποσφαλμάτωσης: 'trace _ id '/' request _ id', stable 'error _ code'.
Ασφάλεια: SQL/στοίβα ίχνη/ρυθμίσεις δεν θα διαρρέουν.
Παρατήρηση: υποβολή εκθέσεων σχετικά με την ταξινόμηση σφαλμάτων (επικύρωση, ποσοστώσεις, χρονοδιαγράμματα κ.λπ.).

2) Βασικές αρχές

1. Ένα ενιαίο μορφότυπο απόκρισης για όλα τα 4xx/5xx (και για τα 2xx με μερικά σφάλματα - ένα ξεχωριστό σχήμα).
2. Καθαρισμός σημασιολογίας HTTP: η σωστή κατάσταση είναι πιο σημαντική.
3. Δύο επίπεδα κώδικα: μεταφορά ('status') και πεδίο σταθερό 'error _ code'.
4. Retribable vs Non-retrible: προσδιορίστε ρητά και δώστε μια υπόδειξη για το back-off.
5. Προεπιλεγμένη ασφάλεια: λεπτομέρειες - μόνο για τον πελάτη με δικαιώματα· χωρίς εσωτερικά ίχνη.
6. Τοπικοποίηση: ο κώδικας μηχανών παραμένει σταθερός, κείμενο - μεταφράζουμε.

3) Ενιαίο μορφότυπο σφάλματος (βάσει RFC 7807)

json
{
"type": "https://api. example. com/errors/validation_failed",
"title": "Validation failed",
"status": 422,
"error_code": "VAL_001",
"detail": "Field 'email' must be a valid address",
"instance": "req_01HZY...93",
"trace_id": "a1b2c3d4e5f6",
"retriable": false,
"errors": [
{"field": "email", "code": "email_invalid", "message": "Invalid email"}
],
"hint": "Fix payload and retry",
"meta": {"docs": "https://docs. example. com/errors#VAL_001"}
}

Απαιτείται: 'type', 'title', 'status', 'error _ code', 'trace _ id'.
Προαιρετικά: 'σφάλματα []' (από πεδία), 'επαναφορτιζόμενα', 'υπόδειξη', 'μετα'.

• 'Τύπος περιεχομένου: εφαρμογή/πρόβλημα + json'
• «X-Request-ID »/« Traceparent» (W3C)
• (για 429/503) «Επανάληψη» (δευτερόλεπτα ή ημερομηνία)

4) Σημασιολογία των καταστάσεων HTTP (συγχώνευση «κλασικών» και πρακτικής)

2xx (επιτυχία)

200 OK είναι μια κοινή επιτυχία.
Δημιουργήθηκε 201 - Τοποθεσία.
202 Αποδεκτή - ασύγχρονα στην ουρά (δώστε 'status _ url').
Multi-Status - μερική επιτυχία (αποφύγετε αν είναι δυνατόν).

4xx (σφάλμα πελάτη)

400 Κακή αίτηση - σύνταξη/μορφή, αλλά όχι επικύρωση πεδίου (κατά προτίμηση 422).
401 Μη εξουσιοδοτημένη - όχι/άκυρη μάρκα. Ας 'WWW-Authenticate'.
403 Απαγορευμένη - η μάρκα είναι έγκυρη, αλλά δεν υπάρχουν αρκετά δικαιώματα (RBAC/ABAC/όρια).
Δεν Βρέθηκε 404 - κανένας πόρος/τελικό σημείο.
409 Σύγκρουση - βέλτιστο κλείδωμα, ιδεατότητα.
Έφυγε - τελικό σημείο μόνιμα αφαιρεθεί.
Η προϋπόθεση απέτυχε - ETag/If-Match απέτυχε.
415 Μη υποστηριζόμενος τύπος πολυμέσων - Άκυρος 'τύπος περιεχομένου'.
422 Μη αποδοτική οντότητα - επικύρωση των επιχειρηματικών κανόνων.
429 Πάρα πολλές αιτήσεις - υπέρβαση ποσοστώσεων/ταχύτητας (βλέπε § 7).

5xx (σφάλμα εξυπηρετητή)

Σφάλμα εσωτερικού εξυπηρετητή 500 - ξαφνικό σφάλμα; να μην αποκαλύπτονται στοιχεία.
502 Κακή πύλη - Σφάλμα ανάντη.
503 Μη διαθέσιμη υπηρεσία - υποβάθμιση/υπερφόρτωση, δώστε 'Retry-After'.
504 Χρονοδιάγραμμα πύλης - χρονοδιάγραμμα υποστήριξης.

5) Ταξινόμηση τομέα 'error _ code'

• 'AUTH _' - πιστοποίηση/εξουσιοδότηση.
• «VAL _» - επικύρωση δεδομένων εισόδου.
• 'RATELIMIT _' - ποσοστώσεις και ταχύτητα.
• 'IDEMP _' - ταυτότητα/αντίγραφα.
• 'CONFLICT _' - εκδόσεις/καθεστώς.
• 'DEP _' - εξαρτήσεις (PSP/DNS/SMTP).
• «PAY _» - επιχειρηματικά σφάλματα του τομέα πληρωμών.
• «SEC _» - ασφάλεια (υπογραφές, HMAC, mTLS).
• «INT _» - εσωτερικό ξαφνικό.

• Σταθερότητα με την πάροδο του χρόνου (back-compat).
• Περιγραφές και παραδείγματα στον κατάλογο σφαλμάτων (docs + machine-readable JSON).

6) Ανακτήσιμο έναντι μη ανακτήσιμο

• «ανακτήσιμο: αληθινό»
• Αν 'αληθεύει' - απαραίτητα 'Retry-After' (σε δευτερόλεπτα) ή συμβόλαιο 'εκθετική back-off (ξεκινώντας από 1-2 s, μέγιστο 30-60 s) ".

Επαναφορτιζόμενο συνήθως: '502/503/504', περίπου '500', '429' (μετά το παράθυρο).
Μη ανακτήσιμο: '400/401/403/404/ 409/410/415/422'.

7) Όρια ποσοστώσεων και σφάλματα ποσοστώσεων (429)

json
{
"type": "https://api. example. com/errors/rate_limited",
"title": "Rate limit exceeded",
"status": 429,
"error_code": "RATELIMIT_RPS",
"detail": "Too many requests",
"retriable": true
}

• 'Retry-After: 12'
• Οριακό όριο X- , «Όριο X- που απομένει», «Όριο X- »
• : «X-Ποσόστωση-Όριο», «X-Ποσόστωση-Υπόλοιπο», «X-Ποσόστωση-Επαναφορά»

8) Ιδιαιτερότητα και συγκρούσεις

Σε γραπτές αιτήσεις - 'Idempotency-Key' (μοναδικό εντός 24-72 ωρών).
Retry σύγκρουση → 409 Σύγκρουση με 'error _ code: "IDEMP_REPLAY"'.
Η διαμάχη έκδοσης πόρων για το ETag → 412 απέτυχε.
Στην απάντηση επισυνάψτε ένα 'resource _ i /' status _ url' για μια ασφαλή νέα αίτηση.

9) Επικύρωση και 422

json
{
"status": 422,
"error_code": "VAL_001",
"errors": [
{"field":"email","code":"email_invalid","message":"Invalid email"},
{"field":"age","code":"min","message":"Must be >= 18"}
]
}

• Μην επαναλαμβάνετε το ίδιο στα 400 - 422 που προτιμώνται για την επικύρωση της επιχείρησης.
• Τα μηνύματα είναι αναγνώσιμα από τον άνθρωπο. Ο «κώδικας» είναι μηχαναγνώσιμος.

10) Ασφάλεια σφαλμάτων

Ποτέ: στοίβα ίχνη, SQL, μονοπάτια αρχείων, ονόματα ιδιωτικών ξενιστών.
Επεξεργασία του PII. παρακολουθούν το GDPR/DSAR.
Για υπογραφή/HMAC, γίνεται διάκριση μεταξύ 'SEC _ SIGNATURE _ MISMATCH' (403) και 'SEC _ TIMESTAMP _ SKEW' (401/403) με την άμεση «check ± time 5 min».

11) Συσχέτιση και παρατηρησιμότητα

Πάντα προσθήκη 'trace _ id '/' X-Request-ID' και κύλιση μέσω των αρχείων καταγραφής/κομματιών.
Συγκεντρωτικά σφάλματα κατά 'error _ code' and 'status' → ταμπλό «κορυφαία σφάλματα», «νέα εναντίον γνωστών».
Προειδοποιήσεις: 5xx/422/429 ακίδα, p95 καθυστέρηση, μερίδιο σφαλμάτων.

12) gRPC/GraphQL/Webhooks - χαρτογραφήσεις

gRPC ↔ HTTP

GraphQL

Μεταφορά 200, αλλά 'σφάλματα []' μέσα - προσθήκη 'extensions. κωδικός "и" trace _ id ".
Για «θανατηφόρα» (επαλήθευση ταυτότητας/ποσοστώσεις) - μια πραγματική 401/403/429 HTTP είναι καλύτερη.

Webhooks

Θεωρήστε επιτυχείς μόνο 2xx παραλήπτες.
Retrai με εκθετική back-off, 'X-Webhook-ID', 'X-Signature'.
410 από τον λήπτη - επανάληψη διακοπής (αφαιρέθηκε το τελικό σημείο).

13) Έκδοση λάθους

'type '/' error _ code' - σταθερό· νέο - μόνο προσθήκη.
Κατά την αλλαγή του σχήματος του σώματος, αυξήστε τη μικρή έκδοση του API ή 'πρόβλημα + json? v = 2 '.
Τεκμηρίωση: πίνακας κωδικών + παραδείγματα. λάθη changelog.

14) Τεκμηρίωση (θραύσματα OpenAPI)

Συνολικές απαντήσεις

yaml components:
responses:
Problem:
description: Problem Details content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
schemas:
Problem:
type: object required: [type, title, status, error_code, trace_id]
properties:
type: { type: string, format: uri }
title: { type: string }
status: { type: integer }
error_code: { type: string }
detail: { type: string }
instance: { type: string }
trace_id: { type: string }
retriable: { type: boolean }
errors:
type: array items:
type: object properties:
field: { type: string }
code: { type: string }
message: { type: string }

Παράδειγμα τελικού σημείου

yaml paths:
/v1/users:
post:
responses:
'201': { description: Created }
'401': { $ref: '#/components/responses/Problem' }
'422': { $ref: '#/components/responses/Problem' }
'429': { $ref: '#/components/responses/Problem' }
'500': { $ref: '#/components/responses/Problem' }

15) Δοκιμές και ποιότητα

Σύμβαση δοκιμής: αντιστοιχία 'application/problem + json', απαιτούμενα πεδία.
Αρνητικές δοκιμές: όλοι οι κλάδοι 401/403/404/ 409/422/429/500.
Χάος/λανθάνουσα κατάσταση: έλεγχος των ρετιρέ για 5xx/ 503/504/429 ('Retry-After').
Δοκιμές ασφαλείας: χωρίς εσωτερικά μηνύματα, σωστή μάσκα PII.
Οπισθοδρόμηση: Οι παλιοί πελάτες κατανοούν νέα πεδία (προσθέστε, μην σπάσετε).

16) Κατάλογος ελέγχου εφαρμογής

• Ενιαίο 'πρόβλημα + json' + σταθερό 'error _ code'.
• Διορθώστε τη σημασιολογία HTTP/gRPC/GraphQL.
• Ανακτήσιμες/μη ανακτήσιμες + «Retry-After »/εφεδρικές συστάσεις.
• Κεφαλίδες ορίου ταχύτητας και 429 συμπεριφορά.
• Idempotency ('Idempotency-Key', 409/412).
• Ασφάλεια: χωρίς ίχνη/μυστικά στοίβας, έκδοση PII.
• «trace _ id »/« X-Request-ID» σε όλα τα σφάλματα.
• Τεκμηρίωση καταλόγου σφαλμάτων και παραδείγματα.
• Παρακολούθηση με ταξινόμηση σφαλμάτων.
• Αυτοτελείς αναλύσεις αρνητικών σεναρίων.

17) Mini-FAQ

Πώς διαφέρουν 400 από 422

400 - αποτυχημένο αίτημα (τύπος σύνταξης/περιεχομένου). 422 - ισχύει στη σύνταξη, αλλά οι επιχειρηματικοί κανόνες δεν εγκρίθηκαν.

Πότε είναι το 401 και πότε το 403

401 - καμία/εσφαλμένη ένδειξη· 403 - υπάρχει ένα σύμβολο, δεν υπάρχουν αρκετά δικαιώματα.

Χρειάζεται το Retry-After 'always

Για το 429/503, ναι; για τα υπόλοιπα, ανακτήσιμα - είναι σκόπιμο να διατυπωθεί ρητή σύσταση.

Σύνολο

Καλά σχεδιασμένα σφάλματα είναι η σύμβαση: σωστή κατάσταση HTTP, ενιαίο 'πρόβλημα + json', σταθερό 'error _ code', σαφείς υποδείξεις retray, και ισχυρή ασφάλεια. Τυποποιήστε τη μορφή, τεκμηριώστε την ταξινομία, προσθέστε τηλεμετρία και δοκιμές - και το API σας γίνεται προβλέψιμο, ασφαλές και φιλικό προς τον ολοκληρωμένο.