Σφάλματα και ανάκαμψη

Χρησιμοποιείτε σταθερούς κωδικούς σφάλματος για να αποφασίσετε αν θα διορθώσετε, θα περιμένετε ή θα επαναλάβετε.

Τι να κάνετε

Η λογική του προγράμματος πρέπει να βασίζεται στην κατάσταση HTTP και στο error.code, όχι στο αναγνώσιμο error.message.
Το 401 απαιτεί έγκυρο έλεγχο ταυτότητας, το 403 αλλαγές πρόσβασης ή προγράμματος και το 409 έλεγχο της λειτουργίας ή της έκδοσης πόρου που βρίσκεται σε σύγκρουση.

Άρνηση πρόσβασης και επανάληψη

401: Το 401 δεν σημαίνει πάντα ότι το διακριτικό έληξε. Αν έληξε, λάβετε νέο και επαναλάβετε την ανάγνωση το πολύ μία φορά. Αν η λήψη διακριτικού επιστρέψει 401, ελέγξτε το κλειδί και σταματήστε τις αυτόματες προσπάθειες.
403: Για 403, ελέγξτε δικαιώματα, περιορισμούς IP και πρόγραμμα συνδρομής. Ένα νέο διακριτικό δεν επαναφέρει ανακληθείσα πρόσβαση.

Έλεγχος ταυτότητας

Πολιτική επανάληψης

Για προσωρινές αποτυχίες χρησιμοποιείτε περιορισμένες επαναλήψεις με αυξανόμενη και τυχαία καθυστέρηση.
Τηρείτε το Retry-After όταν παρέχεται.
Αν μια εγγραφή λήξει λόγω χρονικού ορίου, το αποτέλεσμα μπορεί να είναι άγνωστο.
Διατηρείτε το ίδιο Idempotency-Key και αμετάβλητο αίτημα όταν επαναλαμβάνετε τη λογική λειτουργία.
Ο παρακάτω κατάλογος εξηγεί κάθε δημοσιευμένο κωδικό σφάλματος.

Ασφαλείς εγγραφές

Όρια αιτημάτων

422 / 409

Για τις τιμές, μη έγκυρη μορφή νομίσματος ή ακρίβεια ποσού επιστρέφει 422 request.validation_failed.
Ένας έγκυρος κωδικός νομίσματος που διαφέρει από τον επιλεγμένο τιμοκατάλογο επιστρέφει 409 resource.version_conflict.
Ελέγξτε το πλαίσιο και τις εκδόσεις πριν δοκιμάσετε ξανά.

Κατάλογος σφαλμάτων

400request.malformedΔεν είναι δυνατή η ανάλυση του αιτήματος.

Τι να κάνετε: Ελέγξτε τη σύνταξη JSON, την κωδικοποίηση URL και τη δομή του αιτήματος.
Πολιτική επανάληψης: Δοκιμάστε ξανά αφού διορθώσετε το αίτημα.

JSON

{
  "error": {
    "code": "request.malformed",
    "fields": null,
    "message": "The request could not be read."
  },
  "meta": {
    "request_id": "example-request"
  }
}

401authentication.invalid_credentialsΤο κλειδί API ή το διακριτικό πρόσβασης είναι άκυρο, έχει λήξει ή έχει ανακληθεί.

Τι να κάνετε: Ελέγξτε το URL του καταστήματος και το διαπιστευτήριο. Λάβετε νέο διακριτικό με ενεργό κλειδί API.
Πολιτική επανάληψης: Δοκιμάστε ξανά αφού διορθώσετε τον έλεγχο ταυτότητας· αποφύγετε επαναλαμβανόμενα αιτήματα με άκυρα διαπιστευτήρια.

JSON

{
  "error": {
    "code": "authentication.invalid_credentials",
    "fields": null,
    "message": "The credentials are invalid."
  },
  "meta": {
    "request_id": "example-request"
  }
}

401authentication.requiredΛείπει η απαιτούμενη κεφαλίδα Authorization ή το σχήμα της είναι λανθασμένο.

Τι να κάνετε: Χρησιμοποιήστε ApiKey για τη λήψη διακριτικού και Bearer για λειτουργίες πόρων.
Πολιτική επανάληψης: Δοκιμάστε ξανά αφού προσθέσετε τη σωστή κεφαλίδα.

JSON

{
  "error": {
    "code": "authentication.required",
    "fields": null,
    "message": "Authentication is required."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.client_ip_unverifiedΗ υπηρεσία δεν μπόρεσε να προσδιορίσει αξιόπιστη διεύθυνση IP πελάτη.

Τι να κάνετε: Ζητήστε από τον διαχειριστή του καταστήματος να ελέγξει τη διαδρομή εισόδου. Μην προσθέτετε μόνοι σας κεφαλίδες προώθησης.
Πολιτική επανάληψης: Δοκιμάστε ξανά αφού αποκατασταθεί η έμπιστη διαδρομή σύνδεσης.

JSON

{
  "error": {
    "code": "authorization.client_ip_unverified",
    "fields": null,
    "message": "The client IP address could not be verified."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.ip_not_allowedΗ διεύθυνση IP προέλευσης δεν περιλαμβάνεται στη λίστα επιτρεπόμενων διευθύνσεων του κλειδιού.

Τι να κάνετε: Χρησιμοποιήστε εγκεκριμένη διεύθυνση προέλευσης ή ζητήστε από εξουσιοδοτημένο διαχειριστή να αλλάξει τη λίστα IP του κλειδιού.
Πολιτική επανάληψης: Δοκιμάστε ξανά μόνο αφού επιτραπεί η διεύθυνση.

JSON

{
  "error": {
    "code": "authorization.ip_not_allowed",
    "fields": null,
    "message": "Access from this IP address is not allowed."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.scope_deniedΤο κλειδί δεν διαθέτει ενεργό δικαίωμα που απαιτεί η λειτουργία.

Τι να κάνετε: Ελέγξτε τα υποχρεωτικά και υπό προϋποθέσεις δικαιώματα της λειτουργίας, τα δικαιώματα του κλειδιού και την πρόσβαση του εκδότη.
Πολιτική επανάληψης: Δοκιμάστε ξανά αφού εξουσιοδοτημένος διαχειριστής παραχωρήσει την απαιτούμενη πρόσβαση.

JSON

{
  "error": {
    "code": "authorization.scope_denied",
    "fields": null,
    "message": "The required permission has not been granted."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.api_disabledΗ πρόσβαση API είναι απενεργοποιημένη για αυτό το κατάστημα.

Τι να κάνετε: Ζητήστε από τον ιδιοκτήτη να ελέγξει το ενεργό πρόγραμμα και τη διαθεσιμότητα API.
Πολιτική επανάληψης: Μην επαναλάβετε το αίτημα πριν ενεργοποιηθεί η πρόσβαση API.

JSON

{
  "error": {
    "code": "entitlements.api_disabled",
    "fields": null,
    "message": "API access is disabled for this store."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.limit_exceededΗ αλλαγή θα υπερέβαινε κάποιο όριο του τρέχοντος προγράμματος.

Τι να κάνετε: Ελέγξτε το ισχύον όριο πόρων και προσαρμόστε την αλλαγή ή το πρόγραμμα.
Πολιτική επανάληψης: Δοκιμάστε ξανά αφού επιλυθεί το πρόβλημα ορίου· χρησιμοποιήστε νέο κλειδί ιδιοδυναμίας αν αλλάξει το αίτημα.

JSON

{
  "error": {
    "code": "entitlements.limit_exceeded",
    "fields": null,
    "message": "The operation exceeds a plan limit."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.operation_disabledΤο τρέχον πρόγραμμα δεν περιλαμβάνει αυτή τη λειτουργία.

Τι να κάνετε: Ελέγξτε το ελάχιστο πρόγραμμα που αναφέρεται για τη λειτουργία.
Πολιτική επανάληψης: Δοκιμάστε ξανά όταν το πρόγραμμα επιτρέπει τη λειτουργία και το κλειδί διαθέτει τα απαιτούμενα δικαιώματα.

JSON

{
  "error": {
    "code": "entitlements.operation_disabled",
    "fields": null,
    "message": "The current plan does not allow this operation."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.resource_blockedΈνα όριο προγράμματος αποκλείει τον συγκεκριμένο πόρο.

Τι να κάνετε: Ζητήστε από τον ιδιοκτήτη να άρει τον περιορισμό προγράμματος για τον πόρο.
Πολιτική επανάληψης: Μην επαναλαμβάνετε το ίδιο αίτημα όσο ο πόρος παραμένει αποκλεισμένος.

JSON

{
  "error": {
    "code": "entitlements.resource_blocked",
    "fields": null,
    "message": "A plan limit blocks access to this resource."
  },
  "meta": {
    "request_id": "example-request"
  }
}

404resource.not_foundΟ πόρος απουσιάζει, έχει διαγραφεί ή δεν είναι διαθέσιμος με το συγκεκριμένο αναγνωριστικό.

Τι να κάνετε: Ελέγξτε το κατάστημα, τη διαδρομή πόρου και το αναγνωριστικό. Χρησιμοποιήστε αναγνωριστικά που επιστρέφει αυτό το κατάστημα.
Πολιτική επανάληψης: Δοκιμάστε ξανά μόνο αφού διορθώσετε τον στόχο ή επιβεβαιώσετε ότι υπάρχει.

JSON

{
  "error": {
    "code": "resource.not_found",
    "fields": null,
    "message": "The resource was not found."
  },
  "meta": {
    "request_id": "example-request"
  }
}

405request.method_not_allowedΤο endpoint δεν υποστηρίζει αυτή τη μέθοδο HTTP.

Τι να κάνετε: Χρησιμοποιήστε την τεκμηριωμένη μέθοδο· η κεφαλίδα Allow υποδεικνύει τις υποστηριζόμενες μεθόδους.
Πολιτική επανάληψης: Μην επαναλάβετε τη μη υποστηριζόμενη μέθοδο.

JSON

{
  "error": {
    "code": "request.method_not_allowed",
    "fields": null,
    "message": "This method is not supported for this resource."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409idempotency.key_reusedΑυτό το κλειδί ιδιοδυναμίας ανήκει σε διαφορετικό αίτημα.

Τι να κάνετε: Εντοπίστε την αρχική λειτουργία. Χρησιμοποιήστε νέο κλειδί μόνο για σκόπιμα νέα λογική λειτουργία.
Πολιτική επανάληψης: Μην επαναλάβετε αλλαγμένα δεδομένα με το κλειδί που προκαλεί τη σύγκρουση.

JSON

{
  "error": {
    "code": "idempotency.key_reused",
    "fields": null,
    "message": "This idempotency key was used with a different request."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.already_existsΜια μοναδική τιμή συγκρούεται με υπάρχοντα πόρο.

Τι να κάνετε: Διαβάστε τον υπάρχοντα πόρο και αποφασίστε αν θα τον χρησιμοποιήσετε ή θα επιλέξετε διαφορετική μοναδική τιμή.
Πολιτική επανάληψης: Μην επαναλαμβάνετε την ίδια δημιουργία που προκαλεί σύγκρουση.

JSON

{
  "error": {
    "code": "resource.already_exists",
    "fields": null,
    "message": "A resource with these unique values already exists."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.in_useΆλλοι πόροι εξακολουθούν να εξαρτώνται από αυτόν τον πόρο.

Τι να κάνετε: Ελέγξτε τις εξαρτήσεις και αφαιρέστε ή αλλάξτε τις μέσω υποστηριζόμενων λειτουργιών πριν από τη διαγραφή.
Πολιτική επανάληψης: Δοκιμάστε ξανά αφού επιλυθούν οι εξαρτήσεις.

JSON

{
  "error": {
    "code": "resource.in_use",
    "fields": null,
    "message": "The resource is still in use."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.state_conflictΗ τρέχουσα επιχειρησιακή κατάσταση εμποδίζει αυτή την αλλαγή.

Τι να κάνετε: Διαβάστε την τρέχουσα κατάσταση και επιλέξτε έγκυρη μετάβαση.
Πολιτική επανάληψης: Μην επιβάλλετε αυτόματα και μην υποβάλλετε επανειλημμένα την αλλαγή που προκαλεί σύγκρουση.

JSON

{
  "error": {
    "code": "resource.state_conflict",
    "fields": null,
    "message": "The current resource state does not allow this operation."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.version_conflictΜια άλλη εγγραφή άλλαξε τον πόρο μετά την έκδοση που διαβάσατε.

Τι να κάνετε: Διαβάστε την πιο πρόσφατη κατάσταση, προσαρμόστε την αλλαγή σας και υποβάλετε τη νέα expected_version.
Πολιτική επανάληψης: Χρησιμοποιήστε νέο κλειδί ιδιοδυναμίας για την αναθεωρημένη λειτουργία· μην αντικαθιστάτε δεδομένα χωρίς έλεγχο.

JSON

{
  "error": {
    "code": "resource.version_conflict",
    "fields": null,
    "message": "The resource version has changed."
  },
  "meta": {
    "request_id": "example-request"
  }
}

413request.too_largeΤο αίτημα υπερβαίνει το όριο μεγέθους.

Τι να κάνετε: Μειώστε τα δεδομένα ή χωρίστε την εργασία σε υποστηριζόμενες επιμέρους λειτουργίες.
Πολιτική επανάληψης: Δοκιμάστε μικρότερες, έγκυρες λειτουργίες με ξεχωριστά κλειδιά ιδιοδυναμίας.

JSON

{
  "error": {
    "code": "request.too_large",
    "fields": null,
    "message": "The request exceeds the size limit."
  },
  "meta": {
    "request_id": "example-request"
  }
}

415request.unsupported_media_typeΟ τύπος περιεχομένου ή η κωδικοποίησή του δεν υποστηρίζεται.

Τι να κάνετε: Για εγγραφές JSON χρησιμοποιήστε Content-Type: application/json και υποστηριζόμενο μη συμπιεσμένο σώμα.
Πολιτική επανάληψης: Δοκιμάστε ξανά αφού διορθώσετε τον τύπο περιεχομένου ή την κωδικοποίηση.

JSON

{
  "error": {
    "code": "request.unsupported_media_type",
    "fields": null,
    "message": "The request media type or encoding is not supported."
  },
  "meta": {
    "request_id": "example-request"
  }
}

422request.validation_failedΈνα ή περισσότερα πεδία ή παράμετροι αποτυγχάνουν στην επικύρωση.

Τι να κάνετε: Εξετάστε το error.fields και ελέγξτε τα υποχρεωτικά πεδία, τη δυνατότητα null, τα αναγνωριστικά και τις επιτρεπόμενες τιμές.
Πολιτική επανάληψης: Υποβάλετε διορθωμένο αίτημα· μια αλλαγμένη εγγραφή αποτελεί νέα λογική λειτουργία.

JSON

{
  "error": {
    "code": "request.validation_failed",
    "fields": null,
    "message": "Some request parameters are invalid."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429capacity.queue_fullΗ σύντομη ουρά του API είναι πλήρης· η εκτέλεση του αιτήματος δεν έχει ξεκινήσει.

Τι να κάνετε: Τοποθετήστε τα αιτήματα σε ουρά και τηρήστε την κεφαλίδα απόκρισης Retry-After.
Πολιτική επανάληψης: Περιμένετε τουλάχιστον Retry-After δευτερόλεπτα και προσθέστε τυχαία καθυστέρηση. Κατά την επανάληψη εγγραφής διατηρήστε το αρχικό κλειδί και τα δεδομένα.

JSON

{
  "error": {
    "code": "capacity.queue_full",
    "fields": null,
    "message": "The API is busy. Please retry shortly."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429capacity.wait_timeoutΟ χρόνος αναμονής στην ουρά του API έληξε· η εκτέλεση του αιτήματος δεν έχει ξεκινήσει.

Τι να κάνετε: Τοποθετήστε τα αιτήματα σε ουρά και τηρήστε την κεφαλίδα απόκρισης Retry-After.
Πολιτική επανάληψης: Περιμένετε τουλάχιστον Retry-After δευτερόλεπτα και προσθέστε τυχαία καθυστέρηση. Κατά την επανάληψη εγγραφής διατηρήστε το αρχικό κλειδί και τα δεδομένα.

JSON

{
  "error": {
    "code": "capacity.wait_timeout",
    "fields": null,
    "message": "The API could not start this request in time. Please retry shortly."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429rate_limit.exceededΗ συχνότητα αιτημάτων υπερβαίνει το ισχύον όριο.

Τι να κάνετε: Τοποθετήστε τα αιτήματα σε ουρά και τηρήστε την κεφαλίδα απόκρισης Retry-After.
Πολιτική επανάληψης: Περιμένετε τουλάχιστον Retry-After δευτερόλεπτα και προσθέστε τυχαία καθυστέρηση. Κατά την επανάληψη εγγραφής διατηρήστε το αρχικό κλειδί και τα δεδομένα.

JSON

{
  "error": {
    "code": "rate_limit.exceeded",
    "fields": null,
    "message": "The request rate limit has been exceeded."
  },
  "meta": {
    "request_id": "example-request"
  }
}

500internal.errorΠαρουσιάστηκε μη αναμενόμενο σφάλμα υπηρεσίας.

Τι να κάνετε: Καταγράψτε το αναγνωριστικό αιτήματος και επικοινωνήστε με τον διαχειριστή αν επιμένει το σφάλμα· μην καταγράφετε διαπιστευτήρια στα αρχεία συμβάντων.
Πολιτική επανάληψης: Χρησιμοποιήστε περιορισμένες επαναλήψεις με αυξανόμενη αναμονή. Για εγγραφή διατηρήστε το αρχικό κλειδί ιδιοδυναμίας και αμετάβλητα δεδομένα.

JSON

{
  "error": {
    "code": "internal.error",
    "fields": null,
    "message": "An unexpected error occurred."
  },
  "meta": {
    "request_id": "example-request"
  }
}

502gateway.bad_responseΗ πύλη δεν έλαβε έγκυρη απόκριση API.

Τι να κάνετε: Κρατήστε το αναγνωριστικό αιτήματος. Μια αποτυχημένη απόκριση δεν αποδεικνύει ότι η εγγραφή δεν εφαρμόστηκε.
Πολιτική επανάληψης: Χρησιμοποιήστε περιορισμένες επαναλήψεις με αυξανόμενη αναμονή· επαναλάβετε την ίδια λογική εγγραφή με το αρχικό Idempotency-Key και αμετάβλητα δεδομένα.

JSON

{
  "error": {
    "code": "gateway.bad_response",
    "fields": null,
    "message": "The API gateway could not obtain a valid response."
  },
  "meta": {
    "request_id": "example-request"
  }
}

503service.unavailableΤο API αδυνατεί προσωρινά να εξυπηρετήσει το αίτημα.

Τι να κάνετε: Τηρήστε το Retry-After όταν υπάρχει και κρατήστε το αναγνωριστικό αιτήματος αν η διακοπή επιμένει.
Πολιτική επανάληψης: Χρησιμοποιήστε περιορισμένες επαναλήψεις με αυξανόμενη και τυχαία αναμονή· διατηρήστε το κλειδί και τα δεδομένα όταν επαναλαμβάνετε την ίδια εγγραφή.

JSON

{
  "error": {
    "code": "service.unavailable",
    "fields": null,
    "message": "The API is temporarily unavailable."
  },
  "meta": {
    "request_id": "example-request"
  }
}

504gateway.timeoutΗ πύλη ξεπέρασε το χρονικό όριο αναμονής για το API.

Τι να κάνετε: Κρατήστε το αναγνωριστικό αιτήματος και θεωρήστε το αποτέλεσμα της εγγραφής άγνωστο.
Πολιτική επανάληψης: Χρησιμοποιήστε περιορισμένες επαναλήψεις με αυξανόμενη αναμονή· για εγγραφή διατηρήστε το αρχικό κλειδί ιδιοδυναμίας και τα ίδια δεδομένα.

JSON

{
  "error": {
    "code": "gateway.timeout",
    "fields": null,
    "message": "The API gateway timed out."
  },
  "meta": {
    "request_id": "example-request"
  }
}