Σφάλματα API — Τι σημαίνει κάθε κωδικός και πώς να τον διορθώσετε

Το FastOG επιστρέφει κωδικούς σφάλματος σε μηχανικά αναγνώσιμη μορφή όταν μια αίτηση αποτύχει — είτε πρόκειται για απόδοση υπογεγραμμένου OG image, είτε για κλήση σε μία από τις επιφάνειες διαχείρισης εντός της εφαρμογής. Κάθε απόκριση σφάλματος περιλαμβάνει:

• error — το κληρονομικό σύντομο token. Παραμένει παρόν σε κάθε αποτυχία ώστε να διατηρηθεί η συμβατότητα με παλαιότερους πελάτες.
• code — ο ίδιος σταθερός, τεκμηριωμένος κωδικός σφάλματος (πίνακας παρακάτω), υπό την ονομασία που χρησιμοποιεί το δημόσιο API.
• message — μια περιγραφή ενός προτάσης για το τι πήγε στραβά.
• hint — μια σύντομη περιγραφή σε απλή γλώσσα για το τι πήγε στραβά και πώς να το διορθώσετε.
• docs_url — ένας σύνδεσμος προς αυτή τη σελίδα, με άγκυρα στην ενότητα για αυτόν τον κωδικό.
• request_id — συσχετίζει αυτή την αποτυχία HTTP με μια γραμμή στον πίνακα Render Logs του dashboard (επιστρέφεται επίσης στην κεφαλίδα X-Request-ID). Μια επιφάνεια χωρίς δυνατότητα συσχέτισης επιστρέφει null, αλλά το κλειδί είναι πάντα παρόν.

Οι εντός προϊόντος επιφάνειες — το Shopify admin, το WooCommerce Studio, το γέφυρα Wix και το demo — επιστρέφουν το ίδιο περιβάλλον για τους παρακάτω κωδικούς, οπότε μια αποτυχία σημαίνει το ίδιο πράγμα οπουδήποτε τη συναντήσετε. Μια επιφάνεια module μπορεί να διατηρήσει την τιμή κατάστασης HTTP που έχει επιστρέψει πάντα για έναν κωδικό (για παράδειγμα, το render_failed επιστρέφει 503 στην εξαγωγή cover και 502 στο δημόσιο API); ο κωδικός, το μήνυμα, η ένδειξη και ο σύνδεσμος τεκμηρίωσης δεν αλλάζουν.

Ανάγνωση μιας απόκρισης σφάλματος

{
  "error": "invalid_signature",
  "code": "invalid_signature",
  "message": "The signature does not match.",
  "hint": "The signature did not match. Re-sign with your HMAC secret after every param change.",
  "request_id": "5f2a9c1e-..."
}

Αν λάβετε μια απόκριση που δεν κατανοείτε, η πιο γρήγορη λύση είναι:

1. Σημειώστε το code.
2. Ελέγξτε τον κατασκευαστή διευθύνσεων URL — οι περισσότερες αποτυχίες οφείλονται σε σφάλματα υπογραφής και όχι σε προβλήματα λογαριασμού.
3. Αντιστοιχίστε τον κωδικό παρακάτω για την ακριβή αιτία και τη διόρθωση.
4. Στο ταμπλό, ανοίξτε τα Render Logs και φιλτράρετε με βάση το ίδιο error_code — κάθε γραμμή εμφανίζει τα αιτούμενα παραμέτρα, ώστε να μπορείτε να αναπαράγετε (και να επιβεβαιώνετε ότι το request_id ταιριάζει).

Υπογραφή & ελέγχος ταυτότητας

missing_signature

Λείπουν από το αίτημά σας οι παράμετροι query key και/ή s (υπογραφή).

Διόρθωση: βεβαιωθείτε ότι το URL σας περιλαμβάνει τόσο το key=<api-key> όσο και το s=<hmac-signature>. Χρησιμοποιήστε το SDK ή την αναλυτική καθοδήγηση στο /docs/hmac-signature-guide για να το δημιουργήσετε.

invalid_signature

Η τιμή του s δεν ταίριαζε με αυτή που παράγει το HMAC secret σας για αυτό το URL.

Διόρθωση: η υπογραφή καλύπτει κάθε παράμετρο query εκτός από το s, με τα κλειδιά να είναι ταξινομημένα. Η αλλαγή οποιασδήποτε παραμέτρου — συμπεριλαμβανομένης της αναδιάταξης, διαφορών στην URL-κωδικοποίηση ή προσθήκης κενών — ακυρώνει την υπογραφή. Υπογράψτε ξανά μετά από κάθε αλλαγή. Επιβεβαιώστε ότι το secret είναι το ίδιο με αυτό που εμφανίστηκε κατά τη δημιουργία του API key.

invalid_signature_format

Η τιμή του s δεν είναι ένα hex string 64 χαρακτήρων.

Διόρθωση: η υπογραφή πρέπει να είναι ωτό hex SHA-256 (κεφαλαίο a-f0-9). Αν κάνετε base64-κωδικοποίηση ή περικόπτετε την έξοδο, χρησιμοποιήστε απλό hex.

expired_timestamp

Η χρονική σφραγίδα (timestamp) t που παραστήκατε είναι παλαιότερη των 5 λεπτών.

Διόρθωση: αναγεννήστε τη χρονική σφραγίδα κάθε φορά που δημιουργείτε ένα URL. Αυτός ο κώδικας ισχύει για την παλιά ροή υπογεγραμμένου URL· η τρέχουσα ροή HMAC v2 δεν περιλαμβάνει χρονική σφραγίδα.

invalid_api_key

Το API key key που παραστήκατε δεν υπάρχει.

Διόρθωση: αντιγράψτε το πλήρες API key από το dashboard — είναι το δημόσιο αναγνωριστικό που ξεκινά με το sk_. Είναι δημόσιο και ασφαλές στα URLs· το secret (ποτέ στα URLs) είναι αυτό που αποδεικνύει την κατοχή.

missing_hmac_secret

Το API key δεν έχει ρυθμισμένο HMAC secret.

Διόρθωση: δημιουργήστε ένα νέο API key στο dashboard — το HMAC secret δημιουργείται και εμφανίζεται μία φορά κατά τη δημιουργία.

Παράμετρος / είσοδος

invalid_image_url

Μια ιδιότητα (prop) που περιέχει URL (image, brand_logo, logo, avatar, background_image, ...) δεν είναι δημόσιο http(s) URL.

Διόρθωση: περάστε ένα δημόσια προσβάσιμο https://... URL. Τα localhost, τα ιδιωτικά IP και οι γυμνές διαδρομές απορρίπτονται για την πρόληψη επιθέσεων Server-Side Request Forgery (SSRF).

Εγγραφή

subscription_required (402)

Το αίτημα έφτασε στο Dynamic API, αλλά ο λογαριασμός σας δεν διαθέτει ενεργό πλάνο. Η πρόσβαση στο API είναι αποκλειστικά μέσω εγγραφής: το πλάνο αποτελεί το όριο πρόσβασης και προσφέρει το ίδιο επίπεδο κάλυψης και λειτουργικότητας με αυτά που πωλούνται μέσω των εφαρμογών FastOG. Οι ίδιες οι αναπαραγωγές (renders) δεν μετρώνται — δεν υπάρχει μηνιαίο όριο αναπαραγωγών και δεν επιβάλλονται χρεώσεις για υπερβάλλον χρήση.

Διόρθωση: επιλέξτε ένα πλάνο για το Dynamic API από το dashboard και δημιουργήστε ένα κλειδί API. Η απόκριση περιλαμβάνει ένα top_up_url που οδηγεί στη σελίδα των πλάνων.

Υπηρεσία απόδοσης

store_blocked (403)

Η απόδοση για το κατάστημα πίσω από αυτό το κλειδί έχει παυστεί από τη FastOG (για παράδειγμα, λόγω κατάχρησης ή υπερβολικής χρήσης). Οι εικόνες που έχουν ήδη αποθηκευτεί προσωρινά στο edge μπορεί να συνεχίσουν να σερβίρονται μέχρι να λήξουν. Επικοινωνήστε με την υποστήριξη για να το επιλύσετε· τίποτα που μπορείτε να αλλάξετε στην αίτηση δεν θα το διορθώσει.

render_unreachable

Δεν ήταν δυνατή η πρόσβαση στην υπηρεσία απόδοσης (βραχυπρόθεσμο παράθυρο επανεκκίνησης).

Διόρθωση: δοκιμάστε ξανά μετά από λίγα δευτερόλεπτα. Η απόδοση δεν μετρήθηκε για αυτή την προσπάθεια.

render_failed

Η υπηρεσία απόδοσης επέστρεψε σφάλμα για το αίτημά σας.

Διόρθωση: ελέγξτε τα props του προτύπου σας — μακρές/κακώς διαμορφωμένες τιμές, μη υποστηριζόμενα πεδία ή μη προσβάσιμη εικόνα upstream. Η απόκριση περιλαμβάνει το υποκείμενο status. Η απόδοση δεν μετρήθηκε.

Επιφάνειες διαχείρισης καταστήματος

Αυτοί οι κώδικες αφορούν το Shopify admin και το WooCommerce Studio — τους ενσωματωμένους επεξεργαστές στους οποίους εργάζεται ο έμπορος, αντί για την υπογεγραμμένη API. Ορισμένοι από αυτούς είναι κοινές με την δημόσια API (invalid_image_url, render_failed, invalid_signature); αυτές διατηρούν την εγγραφή που τεκμηριώθηκε παραπάνω.

Γέφυρα Wix

Η γέφυρα Wix υπογράφεται από την εφαρμογή Wix και όχι από μια συνεδρία εμπόρου, επομένως οι αποτυχίες της απευθύνονται στον προγραμματιστή της εφαρμογής. Κάθε απόκριση φέρει ακόμα τα code και request_id· το αναγνωριστικό αιτήματος της γέφυρας είναι αυτό από το υπογεγραμμένο περίβλημα.

Επιφάνεια επίδειξης

Η επίδειξη είναι η κονσόλα πωλήσεων αποκλειστικά για τον ιδιοκτήτη και όχι μια διεπαφή για εμπόρους.

Κώδικες του επεξεργαστή κανόνων με πεδίο εφαρμογής

Οι επεξεργαστές κανόνων με πεδίο εφαρμογής (Shopify admin και WooCommerce Studio) μεταφράζουν αυτομάτως αυτά τα tokens, στη γλώσσα του ίδιου του εμπόρου, οπότε οι απαντήσεις τους περιέχουν error και code αλλά όχι hint — μια δεύτερη περιγραφή στα αγγλικά θα απομακρυνόταν από την τοποποιημένη έκδοση που βλέπει πραγματικά ο έμπορος:

scope_already_defined, scoped_rule_limit_reached, scoped_rules_not_on_plan, scope_value_required, scope_value_too_long, unknown_scope_type, base_rule_required, scoped_rules_product_only, cannot_delete_base_rule.

Ακόμα δυσκολεύεστε;

• Ανοίξτε τη σελίδα Render Logs στο dashboard — κάθε αποτέλεσμα (επιτυχία ή απόρριψη) καταγράφεται με το error_code, την κατάσταση HTTP και τα αιτούμενα παραμέτρους.
• Εκτελέστε το php artisan og:diagnose σε μια υπογεγραμμένη διεύθυνση URL για να ακολουθήσετε ολόκληρη τη διαδικασία και να δείτε ποιο στάδιο αποτυγχάνει.
• Ελέγξτε τα έγγραφα στη πλευρική μπάρα για το πλαίσιο που χρησιμοποιείτε (Next.js, Express, SvelteKit, ...).