Limite și erori

Limite de rată și cotă

Fiecare plan include o limită de rată (cereri pe secundă) și un volum lunar de cereri, publicate pe pagina de prețuri. Limitele se aplică la nivel de cont, împărțite între toate token-urile.

La depășirea limitei de rată, cererea primește status 429 și antetul Retry-After (secunde până poți relua). Depășirea volumului lunar nu oprește brusc contul: primești avertismente, iar la epuizare cererile primesc tot 429, fără costuri neanunțate.

Anteturi de cotă

Fiecare răspuns poartă anteturi de auto-monitorizare, ca să știi unde te afli fără un apel separat:

Formatul răspunsului

Orice răspuns reușit are la nivelul de sus doar data şi, când e cazul, meta. data conţine numai datele cerute; tot ce le descrie — prospeţimea (actualizat), sursa, atribuirea cerută de licenţă, paginarea — stă în meta.

{
    "data": [
        "…"
    ],
    "meta": {
        "paginare": {
            "pagina": 2,
            "per_pagina": 50,
            "total": 137,
            "pagini": 3
        },
        "actualizat": {
            "administrativ": "2026-08-15T16:39:14+00:00"
        }
    }
}

Listele paginate primesc ?pagina= (de la 1) şi ?per_pagina=, iar poziţia vine în meta.paginare: {pagina, per_pagina, total, pagini}. Nu există offset şi nici contoare în data.

„Primele N" — clasamente, cele mai apropiate rezultate, sugestiile unei potriviri semantice, capătul recent al unei serii — se cer cu ?limita=. Nu e paginare: nu există o pagină a doua a unui clasament.

Intervalele se cer cu ?de_la= şi ?pana_la=, ambele incluse, pe orice rută. Acceptă AAAA, AAAA-LL, AAAA-Tn (trimestru) sau AAAA-LL-ZZ, iar ruta le aduce la granularitatea ei: pe o serie zilnică pana_la=2024 înseamnă până la 31 decembrie 2024 inclusiv, pe una anuală de_la=2024-03-01 înseamnă anul 2024.

Unde ruta leagă două puncte, nu un interval — distanţa dintre două localităţi, drumul dintre două firme, un segment de stradă — perechea e ?de= şi ?la=.

Formatul erorilor

Erorile au același plic pe toată platforma: un obiect eroare cu un cod stabil (pentru cod), un mesaj lizibil și, la validare, detalii pe câmpuri. Modulul anaf adaugă în același obiect camp (câmpul vinovat) și request_id (cu care ne poți raporta o eroare), iar la validarea unui document pune alături și errors și warnings. Un client care citește eroare.cod funcționează la fel pe toate modulele.

{
    "eroare": {
        "cod": "validare",
        "mesaj": "Datele trimise nu sunt valide.",
        "detalii": {
            "q": [
                "Trebuie să aibă minim 2 caractere."
            ]
        }
    }
}

Mentenanță (API indisponibil)

Se întâmplă foarte rar și întotdeauna programat — de obicei noaptea, când reindexăm sau integrăm volume mari de date — și durează de regulă doar câteva minute. În aceste ferestre, toate rutele răspund cu status 503 și antetul Retry-After, în același plic de eroare, cu codul mentenanta. Îți poți construi clientul să reia automat după intervalul din Retry-After:

{
    "eroare": {
        "cod": "mentenanta",
        "mesaj": "API-ul este temporar indisponibil."
    }
}

Coduri de status

Semnificația codurilor, comună tuturor rutelor: