Erori

API-ul îți spune imediat, sincron, ce nu e în regulă: nu există validări care durează ore sau răspunsuri care sosesc mai târziu. Fiecare eroare de validare are un cod stabil pe care îl poți folosi în program și o propoziție pentru oameni.

Formatul

Erorile de validare și refuzurile cu motiv folosesc formatul RFC 9457 (Problem Details), cu Content-Type: application/problem+json.

Validare (`422`)

{
  "type": "https://housera.ro/problems/validation",
  "title": "Datele trimise nu sunt valide.",
  "status": 422,
  "errors": [
    { "pointer": "/title", "code": "min", "detail": "Titlul e prea scurt — minim 10 caractere." },
    { "pointer": "/floor", "code": "floor_above_total", "detail": "Etajul 5 nu poate fi mai mare decât numărul total de etaje (4)." },
    { "pointer": "/heating_types", "code": "heating_none_exclusive", "detail": "…" }
  ]
}

Fiecare element din errors[] are:

string

Câmpul cu problema, ca JSON Pointer: /title, /features/2 (al treilea element din features), /photos/0/key.

string

Codul erorii. E stabil: pe el ramifici în codul tău. Lista e mai jos.

string

Explicația pentru oameni, în limba cererii. Textul se poate schimba oricând; nu-l compara în program.

Un câmp poate avea mai multe erori, fiecare cu elementul ei în errors[].

Refuzuri cu motiv (`409`, `412`)

{
  "type": "https://housera.ro/problems/listing_busy",
  "title": "Anunțul e procesat chiar acum — reîncearcă în câteva momente.",
  "status": 409,
  "code": "listing_busy",
  "detail": "Anunțul e procesat chiar acum — reîncearcă în câteva momente."
}

Aici codul e direct în code, la primul nivel.

Celelalte refuzuri

Toate au aceeași formă, cu code la primul nivel:

Status	`code`	Când
`401`	`unauthenticated`	Lipsește cheia, e greșită, expirată sau revocată, ori contul nu mai e activ.
`403`	`missing_ability`	Cheia nu are dreptul cerut (de exemplu `media:write` pentru poze).
`403`	`forbidden`	Nu ai acces la resursă.
`404`	`not_found`	Resursa nu există sau nu e a ta (un anunț al altcuiva răspunde la fel ca unul inexistent).
`409`	`listing_busy`	Anunțul e procesat chiar acum de altă scriere. Reîncearcă în câteva secunde.
`409`	`listing_action_refused`	Operația e refuzată cu un motiv, spus în `detail` (de exemplu, un anunț cu raportări deschise nu se șterge).
`412`	`listing_changed_meanwhile`	`If-Match` nu mai corespunde: anunțul s-a schimbat între timp.
`429`	`too_many_requests`	Ai depășit limita de cereri. Așteaptă câte secunde spune `Retry-After`.

Limba mesajelor

detail și title vin în română sau în engleză. Alegi limba cu parametrul locale din adresă (?locale=en). Fără el, se folosește limba preferată a contului, apoi antetul Accept-Language, apoi româna. Codurile nu se traduc niciodată.

Codurile de validare pe câmp

Când un câmp, luat singur, nu respectă regula lui, codul e numele regulii:

Cod	Ce înseamnă
`required`	Câmpul e obligatoriu și lipsește (sau e gol).
`required_if`, `required_unless`	Câmpul e obligatoriu pentru tipul de proprietate trimis (de exemplu `floor` la un apartament).
`required_with`, `required_without`	Câmpul e obligatoriu împreună cu altul (de exemplu `label` într-un rând din `unit_types`; `url` sau `key` într-o poză).
`present`	Câmpul trebuie să existe în corp, chiar și gol (de exemplu `photos`).
`string`, `integer`, `numeric`, `boolean`, `array`	Valoarea nu are tipul așteptat.
`decimal`	Numărul are prea multe zecimale (suprafețele au cel mult două).
`min`, `max`, `between`	Valoarea (sau lungimea textului, sau numărul de elemente al listei) e în afara limitelor.
`gt`, `gte`	Valoarea trebuie să fie mai mare decât un prag sau decât alt câmp (de exemplu `max_nights` față de `min_nights`).
`size`	Lungimea nu e cea cerută.
`enum`, `in`	Codul nu e în lista valorilor permise. Valorile sunt în vocabular.
`distinct`	Lista conține de două ori aceeași valoare.
`regex`	Formatul nu e cel cerut (de exemplu `price_currency` nu are trei litere mari).
`date_format`	Data sau ora nu au formatul cerut (`AAAA-LL-ZZ`, `HH:MM`).
`url`	Adresa nu e un URL valid sau nu are schema cerută (pozele cer `https`).
`email`	Adresa de email nu e validă.
`prohibits`	Câmpul nu poate fi trimis împreună cu altul (de exemplu `upfront_percent` cu `upfront_cost`).
`iso_country`	`country` nu e un cod de țară ISO 3166-1 alpha-2.
`meaningful_text`	Titlul sau descrierea nu au conținut real (de exemplu un grup de litere repetat).
`phone_number_valid`	`contact_phone` nu e un număr de telefon valid.
`valid_parcel_ring`	Conturul parcelei (`parcel`) nu formează un poligon valid.
`invalid_value`	O verificare specifică a câmpului a eșuat: un cod de nivel necunoscut în `floor`, o cheie de upload care nu e a ta, o etichetă de poză necunoscută sau o încercare de a schimba `type` ori `transaction` la editare. Explicația e în `detail`.
`invalid`	O eroare fără cod propriu. Explicația e în `detail`.

Codurile verificărilor între câmpuri

Unele reguli privesc mai multe câmpuri deodată. Codul lor e specific regulii, iar pointer arată câmpul de corectat.

Cod	Câmp	Ce înseamnă
`transaction_invalid_for_type`	`/transaction`	Tranzacția nu există pentru tipul de proprietate (de exemplu regim hotelier la un teren) sau nu e deschisă acum pe platformă.
`floor_above_total`	`/floor`	Etajul (pentru duplex sau triplex, ultimul nivel al locuinței) e mai mare decât numărul total de etaje.
`upfront_above_price`	`/upfront_cost`	Avansul cerut e mai mare decât prețul.
`below_type_minimum`	câmpul numeric	Valoarea e sub minimul pentru tipul de proprietate (suprafață, etaje, camere, an).
`above_type_maximum`	câmpul numeric	Valoarea e peste maximul pentru tipul de proprietate.
`bedrooms_above_rooms`	`/bedrooms`	Sunt mai multe dormitoare decât camere.
`built_above_land`	`/built_area_sqm`	Suprafața construită a casei depășește suprafața terenului înmulțită cu numărul de niveluri.
`unfurnished_with_appliances`	`/furnished`	Proprietatea e declarată nemobilată, dar dotările includ electrocasnice.
`required`	`/partitioning`	Compartimentarea e obligatorie la un apartament care nu e garsonieră și are mai mult de o cameră.
`heating_none_exclusive`	`/heating_types`	„Fără încălzire” (`none`) nu poate fi combinat cu alte surse de încălzire.
`delivery_in_past`	`/delivery_quarter`	Termenul de livrare al unui ansamblu neterminat e deja trecut.
`complex_needs_complete_type`	`/unit_types`	Un ansamblu are nevoie de cel puțin un tip de unitate complet (denumire, suprafață, număr de unități, preț).
`area_to_below_from`	`/unit_types/N/area_sqm_to`	Suprafața maximă a unui tip de unitate e mai mică decât cea minimă.
`floor_range_invalid`	`/unit_types/N/floors`	Intervalul de etaje al unui tip de unitate nu se încadrează în regimul de înălțime al ansamblului.
`price_currency_not_offered`	`/price_currency`	Moneda nu e una din cele acceptate (vezi `currencies` în vocabular).
`price_currency_unavailable`	`/price_currency`	Nu există momentan un curs pentru moneda trimisă, deci prețul nu poate fi convertit. Reîncearcă mai târziu sau trimite prețul în altă monedă.
`price_above_cap`	`/price`	Prețul, convertit în euro, depășește plafonul platformei.

Codurile de refuz

Status	Cod	Ce înseamnă	Ce faci
`409`	`listing_busy`	Altă scriere lucrează chiar acum pe același anunț. Nu s-a scris nimic.	Reîncerci după o secundă sau două.
`409`	`listing_action_refused`	Acțiunea nu e permisă dintr-un motiv explicat în `detail` (de exemplu, ștergerea unui anunț cu raportări deschise).	Citești `detail`; reîncercarea imediată nu ajută.
`412`	`listing_changed_meanwhile`	`If-Match` conține o versiune veche: anunțul s-a schimbat între timp.	Citești anunțul din nou și retrimiți cu noul `ETag`. Vezi Editarea.

Statusurile HTTP

Status	Când
`200 OK`	Citire sau scriere reușită.
`201 Created`	Anunț nou creat (`POST /listings`, `PUT /listings/ref/{ref}` cu id nou).
`202 Accepted`	Primit, se procesează mai târziu: o editare pe un anunț publicat (merge la moderare) sau o listă de poze.
`204 No Content`	Anunț șters.
`304 Not Modified`	Vocabularul nu s-a schimbat față de `If-None-Match`.
`401 Unauthorized`	Cheie lipsă, greșită, expirată sau revocată. Vezi Autentificare.
`403 Forbidden`	Cheia nu are dreptul cerut de endpoint, sau anunțul nu poate fi modificat de cont.
`404 Not Found`	Anunțul nu există, nu e al tău, sau acțiunea nu e posibilă din starea lui (de exemplu reactivarea unui anunț care nu e pe pauză). Un anunț al altcuiva răspunde la fel ca unul inexistent.
`409 Conflict`	`listing_busy` sau `listing_action_refused`.
`412 Precondition Failed`	`listing_changed_meanwhile`.
`422 Unprocessable Content`	Date invalide. Vezi `errors[]`.
`429 Too Many Requests`	Ai depășit limita de cereri. Aștepți câte secunde spune antetul `Retry-After`. Vezi Limite.
`5xx`	O problemă de partea Housera. Reîncerci cu pauze tot mai mari; cererile cu `Idempotency-Key` sau pe `PUT /listings/ref/{ref}` sunt sigure de repetat.

Când ceri ajutor pentru o eroare, trimite-ne valoarea antetului X-Request-Id din răspuns. Cu ea găsim cererea exactă. O vezi și tu în jurnalul API.

Început

Concepte

Ghiduri

Referință

Mai departe

Formatul

Validare (`422`)

Refuzuri cu motiv (`409`, `412`)

Celelalte refuzuri

Limba mesajelor

Codurile de validare pe câmp

Codurile verificărilor între câmpuri

Codurile de refuz

Statusurile HTTP

​Formatul

​Validare (422)

​Refuzuri cu motiv (409, 412)

​Celelalte refuzuri

​Limba mesajelor

​Codurile de validare pe câmp

​Codurile verificărilor între câmpuri

​Codurile de refuz

​Statusurile HTTP

Formatul

Validare (`422`)

Refuzuri cu motiv (`409`, `412`)

Celelalte refuzuri

Limba mesajelor

Codurile de validare pe câmp

Codurile verificărilor între câmpuri

Codurile de refuz

Statusurile HTTP