Coduri de eroare

Toate erorile întorc un JSON al cărui obiect error conține code, message și request_id. Codurile sunt stabile; decide după code, niciodată după message. 402 înseamnă o problemă de facturare (cotă sau plată) și se rezolvă cu bani; 429 înseamnă că trimiți prea repede și se rezolvă așteptând Retry-After secunde.

Cod	Status HTTP	Mesaj	Remediere
`invalid_body`	400	Corpul cererii trebuie să fie JSON valid	Trimite JSON valid cu Content-Type: application/json. house_number este string, nu număr.
`invalid_idempotency_key`	400	Idempotency-Key trebuie să aibă 1-255 de caractere ASCII vizibile	Trimite o valoare unică de 1-255 de caractere ASCII vizibile (de exemplu un UUID).
`idempotency_key_reused`	422	Această cheie Idempotency-Key a fost deja folosită cu un alt corp al cererii	Folosește o cheie nouă pentru un corp diferit; reia exact același corp doar cu aceeași cheie.
`invalid_parameter`	400	Parametru invalid sau în afara intervalului permis	Verifică limitele: limit între 1 și 25 (autocomplete, căutare), range și group doar cu valorile documentate (usage).
`invalid_postal_code`	400	Codul poștal trebuie să conțină exact 6 cifre	Trimite exact 6 cifre, fără spații.
`invalid_query`	400	Interogarea trebuie să conțină cel puțin 2 caractere	Trimite q cu cel puțin 2 caractere.
`missing_address`	400	Trimiteți fie „address” (structurat), fie „freeform” (text)	Completează unul dintre cele două câmpuri.
`ambiguous_input`	400	Trimiteți fie „address”, fie „freeform”, nu ambele	Trimite un singur format de adresă.
`missing_locality`	400	Câmpul locality este obligatoriu	Adaugă locality în corpul cererii.
`house_number_requires_street`	400	house_number necesită și street	Trimite street împreună cu house_number.
`invalid_house_number`	400	house_number nu poate fi gol	Omite câmpul sau trimite un număr nevid (string).
`missing_file_url`	400	Câmpul file_url este obligatoriu	Adaugă file_url pentru jobul batch.
`invalid_callback_url`	400	options.callback_url trebuie să fie un URL https pe o gazdă publică	Folosește un URL https public; adresele private, loopback și link-local sunt respinse.
`field_too_long`	400	Câmpurile text trebuie să aibă cel mult 256 de caractere	Scurtează câmpul indicat în mesaj.
`missing_credentials`	401	Autentificare necesară	Trimite Authorization: Bearer YOUR_API_KEY pe fiecare cerere.
`invalid_api_key`	401	Cheie API invalidă sau revocată	Rotește cheia din dashboard și actualizează secretul în mediul tău.
`quota_exceeded`	402	Cota lunară de cereri a fost depășită — treceți la un plan superior pentru a continua	Planurile fără depășire se opresc la cota lunară. Treci pe un plan superior sau așteaptă resetarea (header X-Posty-Period-Resets-At). Nu reîncerca automat.
`payment_required`	402	Plata este restantă — actualizați metoda de plată pentru a continua	Actualizează metoda de plată din dashboard (header X-Posty-Grace-Period-Ends).
`forbidden`	403	Acces interzis	Resursa aparține altei organizații; folosește o cheie a organizației corecte.
`subscription_suspended`	403	Abonamentul este suspendat din cauza neplății	Achită factura restantă din dashboard.
`not_found`	404	Resursa solicitată nu există	Verifică ID-ul trimis.
`postal_code_not_found`	404	Nu există date pentru acest cod poștal	Verifică codul poștal sau folosește căutarea.
`locality_not_found`	404	Localitatea nu a fost găsită	Verifică denumirea localității și județul.
`method_not_allowed`	405	Metodă HTTP nepermisă	Folosește metoda HTTP documentată pentru endpoint.
`job_not_complete`	409	Lucrarea nu este încă finalizată	Interoghează statusul jobului până devine done.
`results_expired`	410	Rezultatele au fost șterse după perioada de retenție	Rezultatele se păstrează 30 de zile după finalizare; retrimite jobul.
`payload_too_large`	413	Corpul cererii depășește 64 KiB	Trimite un corp mai mic sau folosește batch.
`rate_limit_exceeded`	429	Limita de cereri a fost depășită, vă rugăm să reduceți ritmul	Așteaptă câte secunde indică Retry-After și respectă headerele X-RateLimit-*.
`internal_error`	500	Eroare internă de server	Trimite request_id la support@posty.ro pentru investigare.
`request_timeout`	504	Cererea a depășit timpul maxim de procesare — încercați din nou	Reîncearcă cererile idempotente. POST /v1/addresses/batch nu este atomic: o reîncercare poate crea un job duplicat.