Erori API — Ce înseamnă fiecare cod și cum să o repari

FastOG returnează coduri de eroare citibile de mașină atunci când o cerere eșuează — o randare de imagine OG semnată sau un apel către una dintre suprafețele administrative din produs. Fiecare răspuns de eroare include:

• error — tokenul scurt legacy. Încă prezent la fiecare eșec, astfel încât un client mai vechi să continue să funcționeze.
• code — același cod de eroare stabil și documentat (tabelul de mai jos), sub numele folosit de API-ul public.
• message — o descriere de o propoziție a ceea ce a mers greșit.
• hint — o scurtă descriere în limbaj simplu a ceea ce a mers greșit și cum să o repari.
• docs_url — un link către această pagină, ancorat la secțiunea pentru acel cod.
• request_id — corelează acest eșec HTTP cu un rând din tabelul Render Logs din dashboard (returnat și în header-ul răspunsului X-Request-ID). O suprafață fără nimic de corelat răspunde cu null, dar cheia este întotdeauna prezentă.

Suprafețele din produs — adminul Shopify, WooCommerce Studio, puntea Wix și demo-ul — răspund cu același envelope pentru codurile de mai jos, astfel încât un eșec înseamnă același lucru oriunde îl întâlnești. O suprafață de modul poate păstra statusul HTTP pe care l-a returnat dintotdeauna pentru un cod (de exemplu render_failed răspunde cu 503 la exportul copertei și cu 502 la API-ul public); codul, mesajul, hint-ul și link-ul către documentație nu se schimbă.

Citirea unui răspuns de eroare

{
  "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-..."
}

Dacă primești un răspuns pe care nu îl înțelegi, calea cea mai rapidă este:

1. Notează code.
2. Verifică-ți constructorul de URL — majoritatea eșecurilor sunt bug-uri de semnare, nu probleme de cont.
3. Potrivește codul de mai jos pentru cauza și soluția exactă.
4. În dashboard, deschide Render Logs și filtrează după același error_code — fiecare rând afișează parametrii solicitați, astfel încât să poți reproduce (și confirma că request_id corespunde).

Semnare și autentificare

missing_signature

Cererii tale îi lipsesc parametrii de interogare key și/sau s (semnătura).

Remediu: asigură-te că URL-ul tău include atât key=<api-key>, cât și s=<hmac-signature>. Folosește SDK-ul sau ghidul /docs/hmac-signature-guide pentru a-l construi.

invalid_signature

Valoarea s nu corespunde cu ceea ce produce secretul tău HMAC pentru acest URL.

Remediu: semnătura acoperă fiecare parametru de interogare cu excepția s, cu cheile sortate. Modificarea oricărui parametru — inclusiv reordonarea, diferențele de codificare URL sau adăugarea de spații — invalidează semnătura. Resemnează după fiecare modificare. Confirmă că secretul tău este același afișat la crearea cheii API.

invalid_signature_format

Valoarea s nu este un șir hex de 64 de caractere.

Remediu: semnătura trebuie să fie hex SHA-256 brut (a-f0-9 minuscule). Dacă codezi base64 sau trunchiezi rezultatul, folosește hex simplu.

expired_timestamp

Timestamp-ul t pe care l-ai furnizat are mai mult de 5 minute.

Remediu: regenerează timestamp-ul de fiecare dată când construiești un URL. Acest cod se aplică fluxului legacy cu URL semnat; fluxul actual HMAC v2 nu are timestamp.

invalid_api_key

key pe care l-ai transmis nu există.

Remediu: copiază cheia API completă din dashboard — este identificatorul public care începe cu sk_. Este publică și sigură în URL-uri; secretul (niciodată în URL-uri) este cel care dovedește posesia.

missing_hmac_secret

Cheia API nu are niciun secret HMAC configurat.

Remediu: creează o cheie API nouă în dashboard — secretul HMAC este generat și afișat o singură dată la creare.

Parametru / input

invalid_image_url

O proprietate care conține un URL (image, brand_logo, logo, avatar, background_image, ...) nu este un URL public http(s).

Remediere: transmite un URL https://... accesibil public. Localhost, IP-urile private și căile simple sunt respinse pentru a preveni falsificarea cererilor pe partea de server (server-side request forgery).

Abonament

subscription_required (402)

Cererea a ajuns la Dynamic API, dar contul tău nu are niciun plan activ. Accesul la API este doar pe bază de abonament: planul este condiția de acces și oferă aceeași acoperire și aceeași scară de capabilități pe care le vând aplicațiile FastOG. Randările în sine nu sunt contorizate — nu există o cotă lunară de randări și nicio facturare pentru depășire.

Soluție: alege un plan Dynamic API în dashboard și creează o cheie API. Răspunsul include un top_up_url care indică pagina planurilor.

Serviciul de randare

store_blocked (403)

Randarea pentru magazinul din spatele acestei chei a fost suspendată de FastOG (de exemplu, abuz sau utilizare excesivă). Copertele deja cache-uite la edge pot continua să fie servite până la expirare. Contactează suportul pentru a rezolva situația; nimic din ce poți modifica în cerere nu va rezolva asta.

render_unreachable

Serviciul de randare nu a putut fi contactat (fereastră scurtă de repornire).

Soluție: reîncearcă peste câteva secunde. Randarea nu a fost contorizată pentru această încercare.

render_failed

Serviciul de randare a returnat o eroare pentru cererea ta.

Soluție: verifică proprietățile șablonului — valori lungi/malformate, câmpuri neacceptate sau o imagine upstream inaccesibilă. Răspunsul include status subiacent. Randarea nu a fost contorizată.

Suprafețe de administrare ale magazinului

Aceste coduri răspund din adminul Shopify și din WooCommerce Studio — editoarele încorporate în care lucrează un comerciant, nu din API-ul semnat. Câteva sunt comune cu API-ul public (invalid_image_url, render_failed, invalid_signature); acelea păstrează intrarea documentată mai sus.

Bridge Wix

Bridge-ul Wix este semnat de aplicația Wix, nu de o sesiune de comerciant, așa că eșecurile sale sunt adresate dezvoltatorului aplicației. Fiecare răspuns poartă în continuare code și request_id; id-ul cererii bridge este cel din plicul semnat.

Suprafața demo

Demo-ul este consola de vânzări doar pentru proprietar, nu un endpoint pentru comercianți.

Codurile editorului de reguli cu domeniu de aplicare

Editoarele de reguli cu domeniu de aplicare (adminul Shopify și WooCommerce Studio) traduc singure aceste tokenuri, în limba comerciantului, așa că răspunsurile lor conțin error și code, dar nu hint — o a doua descriere în engleză s-ar abate doar de la cea localizată pe care o vede efectiv comerciantul:

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.

Încă blocat?

• Deschide pagina Render Logs din dashboard — fiecare rezultat (succes + respingere) este listat cu error_code, statusul HTTP și parametrii solicitați.
• Rulează php artisan og:diagnose pe un URL semnat pentru a parcurge întregul pipeline și a vedea la ce etapă apare eroarea.
• Verifică documentația din bara laterală pentru framework-ul pe care îl folosești (Next.js, Express, SvelteKit, ...).