Limite și coduri de eroare MCP

Limitele de apeluri, mesajele 401 și codurile de eroare ale uneltelor, cu soluția pentru fiecare.

Serverul MCP BLACKBOX (https://api.app.blackbox.md/mcp) limitează numărul de apeluri și, când ceva nu merge, răspunde cu un mesaj scurt în engleză sau cu un cod de eroare. Aici găsiți limitele, răspunsurile HTTP la conectare (401, 404, 421) și codurile de eroare ale uneltelor, cu ce faceți în fiecare caz. Token-urile se creează și se revocă pe blackbox.md, în „Contul meu” → „Token-uri API” (blackbox.md/account/api-tokens).

Disponibil pentru: orice client blackbox.md care conectează un asistent AI cu un token API.

Limita generală: 120 de apeluri pe minut

Un cont poate face cel mult 120 de apeluri de unelte în orice interval de 60 de secunde. Limita este a contului, nu a token-ului: toate token-urile și toți clienții AI o împart.
Peste limită, unealta răspunde cu eroarea rate_limited. Nu este o eroare HTTP 429: conexiunea rămâne activă, doar apelul este refuzat.
Se numără apelurile din ultimele 60 de secunde, inclusiv cele refuzate. Dacă asistentul reîncearcă în buclă, rămâne blocat. Opriți apelurile și așteptați un minut întreg.
whoami și list_vm_plans nu intră în limită.
Limitele MCP sunt separate de cele ale butoanelor din panou și ale paginilor blackbox.md. Pe acestea le găsiți în Mesajul „Prea multe încercări” și limitele de utilizare.

Limitele fiecărei unelte

Pe lângă limita generală, majoritatea uneltelor au și o limită proprie, tot pe cont. Depășirea dă aceeași eroare, rate_limited. Ce face fiecare unealtă: Lista uneltelor MCP.

Unealtă	Limită
`create_order`	20 pe oră, inclusiv ofertele (`confirm=false`)
`pay_order`	10 pe minut
`cancel_order`	5 în 5 minute, inclusiv previzualizările
`resize_server`	3 în 10 minute, inclusiv previzualizările
`run_server_command`	30 pe minut
`reveal_server_credentials`	20 pe minut
`reset_server_password`	3 în 5 minute
`power_server`	6 pe minut
`get_server_ssh_access`	10 în 5 minute
`add_server_ssh_key`, `remove_server_ssh_key`	câte 10 în 5 minute
`set_server_password_auth`	5 în 5 minute
`list_server_ssh_keys`, `list_ssh_keys`	câte 30 pe minut
`add_ssh_key`	10 pe oră
`delete_ssh_key`	20 pe oră
`list_servers`, `get_server`, `get_balance`	câte 60 pe minut
`list_transactions`, `list_orders`, `list_invoices`	câte 30 pe minut
`get_server_resize_options`	doar limita generală
`whoami`, `list_vm_plans`	fără limită

Atenție Ofertele și previzualizările consumă limita la fel ca acțiunile. Trei previzualizări de upgrade epuizează resize_server pentru 10 minute. Cereți asistentului o singură previzualizare, verificați-o, apoi confirmați.

Erori la conectare (HTTP)

Aceste erori apar înainte ca asistentul să poată folosi vreo unealtă, iar clientul AI arată conexiunea ca eșuată. Motivul exact apare în jurnalul clientului sau la un test cu MCP Inspector ori cu o cerere HTTP: vedeți Folosirea MCP din cod (API-uri AI și HTTP).

401: token lipsă sau nerecunoscut

La orice problemă cu token-ul, serverul răspunde cu HTTP 401 și corpul {"error":"invalid_token","error_description":"…"}. Câmpul error_description arată motivul:

`error_description`	Cauza	Ce faceți
`authorization header missing`	Cererea nu are antetul `Authorization` și nici un antet alternativ cu token-ul.	Adăugați `Authorization: Bearer bbx_pat_…`. În aplicația Claude, verificați antetul `x-api-key`: numele scris exact, valoarea începe cu `bbx_pat_`. Vedeți Conectarea în aplicația Claude (connector personalizat).
`unsupported authorization scheme (expected: Bearer <token>)`	Antetul `Authorization` nu începe cu `Bearer` urmat de spațiu: lipsește cuvântul `Bearer`, are alt cuvânt în față sau după `Bearer` nu urmează nimic.	Scrieți `Bearer`, un spațiu, apoi token-ul. Dacă țineți token-ul într-o variabilă de mediu, verificați că nu este goală.
`bearer token is empty`	După `Bearer` nu urmează niciun token.	Verificați că token-ul (sau variabila de mediu cu el) nu este gol.
`token not recognised (expected a bbx_pat_ personal access token)`	Textul de după `Bearer` nu începe cu `bbx_pat_`: altă cheie, ghilimele în plus sau două spații după `Bearer`.	Copiați token-ul exact, fără ghilimele, cu un singur spațiu după `Bearer`.
`token not recognised (revoked, expired, or unknown)`	Token-ul are forma corectă, dar nu este valid: a fost revocat, a fost creat înainte de ultima schimbare a parolei contului, contul a fost șters sau token-ul a fost copiat incomplet.	Creați un token nou și înlocuiți-l în client (vedeți secțiunea despre parolă de mai jos).

Important Între Bearer și token trebuie să fie exact un spațiu. Cu două spații, token-ul ajunge la server cu un spațiu în față și este respins. Cuvântul Bearer poate fi scris cu litere mari sau mici.

Authorization: Bearer bbx_pat_…

404 și 421

Răspuns	Cauza	Ce faceți
HTTP 404	Adresa are altă cale decât `/mcp` sau serviciul MCP este temporar indisponibil.	Folosiți exact `https://api.app.blackbox.md/mcp`. Dacă adresa este corectă, reîncercați mai târziu, iar dacă eroarea persistă, scrieți-ne: Cum contactați suportul BLACKBOX.
HTTP 421 (Misdirected Request)	Cererea are alt nume de gazdă decât `api.app.blackbox.md`, de exemplu pentru că un proxy a schimbat antetul `Host`.	Folosiți numele `api.app.blackbox.md`, exact ca în adresa de mai sus.

Codurile de eroare ale uneltelor

Când o unealtă nu reușește, asistentul primește un cod scurt, uneori urmat de detalii după „:”, de exemplu missing_scope: this token does not have 'orders:write'. Conexiunea rămâne activă. Dacă asistentul doar rezumă eroarea, cereți-i textul exact.

Erori comune

Cod	Ce înseamnă	Ce faceți
`rate_limited`	S-a depășit limita generală sau limita uneltei.	Opriți apelurile la acea unealtă cât durează fereastra limitei (un minut, 5 minute, 10 minute sau o oră). Nu reîncercați în buclă.
`missing_scope`	Token-ul nu are permisiunea cerută; mesajul o numește.	Creați un token nou cu permisiunea respectivă, puneți-l în client și revocați-l pe cel vechi. Permisiunile unui token existent nu se pot schimba. Vedeți Permisiunile token-urilor (scopes).
`not_found`	ID-ul nu există sau aparține altui cont; cele două cazuri arată la fel intenționat. Același cod apare pentru o acțiune pe un server pe care doar îl vedeți (în panou are eticheta „Administrat”).	Cereți asistentului să ia ID-ul din `list_servers`, `list_orders` sau `list_ssh_keys`. Pentru serverele „Administrat”, scrieți-ne.
`invalid_server_id`, `invalid_order_id`, `invalid_key_id`	ID-ul nu are formatul corect: asistentul a trimis, de exemplu, numele sau IP-ul serverului.	Cereți-i să folosească câmpul `id` din `list_servers`, `list_orders` sau `list_ssh_keys`.
`internal_error`	Eroare neprevăzută la BLACKBOX.	Reîncercați o singură dată. Dacă se repetă, scrieți-ne ora și numele uneltei.
Mesajul că serviciul de infrastructură este temporar indisponibil	La un upgrade sau la anularea unei comenzi cu server, infrastructura nu a răspuns. Nu s-a schimbat nimic și nu s-a debitat nimic.	Reîncercați peste câteva minute. Dacă persistă, scrieți-ne.

Servere și comenzi pe server

Cod	Ce înseamnă	Ce faceți
`invalid_action`	`power_server` a primit o acțiune necunoscută.	Acțiunile valide sunt `reboot`, `stop` și `start`.
`no_instance_id`	Serverul nu este o mașină virtuală pe care BLACKBOX o poate porni sau opri automat (de exemplu, un server înregistrat manual sau un server mai vechi la care contul dvs. are acces). Pe unele dintre aceste servere funcționează doar `reboot`.	Pentru alte acțiuni, scrieți-ne.
`power_action_failed`	Infrastructura nu a executat comanda de pornire, oprire sau repornire.	Verificați starea cu `get_server` (`power_state`) și reîncercați după un minut. Dacă persistă, scrieți-ne.
`reset_failed`	Parola nu a putut fi schimbată, de obicei pentru că serverul este oprit sau nu răspunde. Parola veche rămâne valabilă.	Porniți serverul, așteptați să pornească și reîncercați (cel mult 3 resetări în 5 minute).
`ssh_connection_failed`	Conexiunea de administrare BLACKBOX nu a ajuns la server: serverul este oprit sau încă pornește, SSH nu răspunde, root nu se mai poate autentifica cu cheie sau a fost ștearsă „Cheie de administrare (blackbox.md)”.	Verificați că serverul rulează, așteptați 30–60 de secunde după o repornire și reîncercați o dată. Dacă persistă, vedeți Rularea comenzilor pe server prin AI sau scrieți-ne.
`invalid_command`	Comanda este goală sau are peste 8192 de caractere.	Verificați că apelul conține o comandă. Împărțiți o comandă prea lungă în mai multe apeluri.

Comenzi, plăți, anulări și upgrade

Cod	Ce înseamnă	Ce faceți
`unsupported_os`	Sistemul de operare cerut nu se instalează automat (de exemplu Windows). Mesajul enumeră ID-urile acceptate.	Alegeți unul dintre `ubuntu-24`, `ubuntu-22`, `ubuntu-20`, `debian-12`, `debian-11`, `centos-9`, `almalinux-9`. Windows este disponibil doar la cerere, prin suport.
`configurator_retired`	Configurația personalizată nu mai există: a fost înlocuită de planurile fixe.	Cereți asistentului `list_vm_plans` și alegeți un plan.
`plan_retired`	Planul cerut a fost retras. Mesajul propune cel mai apropiat plan `vm-…`.	Verificați prețul planului propus cu `list_vm_plans` și comandați-l pe acela.
`plan_unavailable`	Configurația hardware a planului este temporar indisponibilă. Comanda nu a fost creată.	Alegeți un plan apropiat din `list_vm_plans` sau reîncercați mai târziu.
`price_changed`	Suma trimisă la `pay_order` nu este prețul curent; mesajul arată prețul corect. Nu s-a debitat nimic.	Verificați noul preț și confirmați plata cu suma corectă.
`insufficient_balance`	Soldul nu acoperă plata sau upgrade-ul. La upgrade, eroarea apare deja la previzualizare. Nu s-a debitat nimic.	Alimentați soldul pe blackbox.md: „Contul meu” → „Sold” → „Alimentează soldul”. Asistentul nu poate face asta. Vedeți Alimentarea soldului.
`not_payable`	Comanda nu mai are statusul „Nou”. Mesajul arată statusul în engleză: `in_progress` = „În lucru”, `done` = „Finalizat”, `cancelled` = „Anulat”.	Verificați comanda în „Contul meu” → „Comenzi”. Nu o plătiți din nou.
`already_settled`	Comanda a fost plătită între timp, de exemplu cu cardul. Nu s-a debitat nimic din sold.	Verificați comanda în „Contul meu” → „Comenzi” sau cereți `list_orders`.
`provisioning_in_progress`	Serverul comenzii se creează chiar acum, deci comanda nu se poate anula.	Așteptați câteva minute, apoi cereți o nouă previzualizare a anulării.
`not_cancellable`	Comanda are statusul „Finalizat” sau „Anulat” și nu se mai poate anula.	Verificați statusul cu `list_orders`. Pentru o comandă finalizată, scrieți-ne.
`state_changed`	Comanda s-a schimbat între previzualizare și confirmare.	Cereți o previzualizare nouă și confirmați-o pe aceea.
`target_not_a_candidate`	Planul ales pentru upgrade nu este printre variantele permise: doar planuri mai mari din aceeași familie.	Cereți asistentului să ruleze din nou `get_server_resize_options` și să aleagă exact una dintre variante.
`job_active`	Un upgrade al acestui server este deja în curs.	Așteptați câteva minute să se termine. Nu porniți un al doilea.
`not_upgradeable_plan`	Planul serverului („VPS hosting” cu panou sau server dedicat) nu se poate mări automat.	Scrieți-ne pentru o configurație mai mare.
`vm_not_resizable`	Serverul este într-o stare de tranziție, de exemplu se creează sau se mărește deja.	Reîncercați peste câteva minute.

Cum funcționează ofertele, plata și anularea prin AI: Comenzi, plăți, anulări și upgrade prin AI.

Chei SSH

Cod	Ce înseamnă	Ce faceți
`management_key_protected`	S-a încercat ștergerea „Cheie de administrare (blackbox.md)” de pe server. Ea nu se poate șterge: prin ea funcționează panoul și asistentul AI.	Nu este nevoie de nicio acțiune. Vedeți Cheile BLACKBOX de pe serverul dvs..
`last_key_on_key_only_server`	Ar fi ștearsă ultima cheie a dvs. de pe un server „Doar cheie” și ați pierde accesul SSH.	Adăugați întâi altă cheie sau activați autentificarea cu parolă, apoi ștergeți cheia.
`no_customer_key_installed`	Autentificarea cu parolă nu poate fi dezactivată: pe server nu este instalată nicio cheie a dvs.	Instalați întâi cheia dvs. pe server (`add_server_ssh_key`), apoi reîncercați.
`operation_in_progress`	Pe același server rulează deja o modificare a cheilor sau a autentificării cu parolă.	Așteptați un minut și reîncercați.
`private_key_submitted`	S-a trimis o cheie privată în locul celei publice. Nu a fost salvată.	Trimiteți conținutul fișierului `.pub`. Cheia privată a ajuns în conversația cu asistentul: considerați-o expusă și generați o pereche nouă (Generarea unei chei SSH (Windows, macOS, Linux)).
`duplicate_key`	Cheia există deja în contul dvs.	Folosiți cheia existentă (`list_ssh_keys`).
`too_many_keys`	Contul are deja 20 de chei, numărul maxim.	Ștergeți o cheie pe care nu o mai folosiți (`delete_ssh_key`), apoi adăugați-o pe cea nouă.
`unsupported_key_type`, `key_too_weak`, `invalid_public_key`	Textul nu este o cheie publică OpenSSH validă, are un tip neacceptat sau este o cheie RSA sub 2048 de biți.	Folosiți o cheie `ssh-ed25519`, RSA de cel puțin 2048 de biți sau ECDSA.

Securitate Nu trimiteți token-ul la suport și nu îl lăsați în capturi de ecran. Pentru o problemă, ne ajung ora, numele uneltei și mesajul de eroare. Dacă un token a ajuns undeva public, revocați-l imediat.

Token-ul nu mai funcționează după schimbarea parolei

Când schimbați parola contului blackbox.md, toate token-urile create înainte de schimbare se opresc, iar clientul AI primește token not recognised (revoked, expired, or unknown). În listă, token-urile vechi rămân fără niciun marcaj.

Pe blackbox.md, deschideți „Contul meu” → „Token-uri API”.
Creați un token nou cu aceleași permisiuni și copiați-l. Pașii: Token-uri API: creare, copiere și revocare.
Înlocuiți token-ul vechi în clientul AI și reconectați clientul.
Cereți asistentului să apeleze whoami: răspunsul confirmă contul și arată permisiunile care lipsesc.
Revocați token-urile vechi cu „Revocă”.

Deconectarea de pe blackbox.md nu oprește token-urile.

Întrebări frecvente

Ieri token-ul mergea, azi primesc 401. De ce? Cauzele posibile: token-ul a fost revocat sau parola contului a fost schimbată între timp. Citiți error_description din răspuns și urmați rândul din tabelul 401.

Asistentul spune că o unealtă nu există. De ce? Clientul AI vede doar uneltele pentru care token-ul are permisiune. Creați un token nou cu permisiunea necesară.

Limitele se resetează la o oră fixă? Nu. Se numără apelurile din ultima fereastră (un minut, 5 minute, 10 minute sau o oră, după limită). După ce opriți apelurile, accesul revine singur.

Butoanele din panou consumă din limitele MCP? Nu. Panoul și MCP au limite separate, chiar și pentru aceleași acțiuni.