Depanarea API: erori comune
Fiecare endpoint din referință este marcat astăzi ca Planned: este contractul publicat și încă nu răspunde. Această pagină listează erorile pe care API-ul le va returna, astfel încât codul tău să le poată gestiona de la prima zi.
Citește mai întâi eroarea #
Fiecare eroare răspunde cu un status 4xx sau 5xx și același corp:
{ "error": { "code": "forbidden", "message": "…" } }message este o propoziție simplă în engleză care spune ce a mers prost. Înregistreaz-o, dar direcționează codul tău după code, niciodată după message.
401 unauthorized #
API-ul nu a acceptat token-ul tău. Verifică, în această ordine:
- Header-ul este exact
Authorization: Bearer <token>, cu cuvântulBearerși un spațiu. - Token-ul a fost copiat complet. Este afișat o singură dată, când îl creezi.
- Token-ul este încă activ. În Users › API & MCP, tabelul Access tokens arată data expirării și statusul fiecărui token, iar Show revoked tokens listează cele vechi.
- Dacă a expirat sau a fost revocat, creează unul nou (sau Rotate-ază-l) și actualizează variabila de mediu.
403 forbidden #
Token-ul este valid, dar îi lipsește permisiunea necesară endpoint-ului. Fiecare endpoint din referință listează permisiunea sa, cum ar fi can_fan_read sau can_sales_read.
- Găsește permisiunea în coloana Permission a endpoint-ului.
- În Users › API & MCP, apasă Edit pe token și bifează permisiunea.
- Apelează
GET /v1/workspace: răspunsul listează ce poate face token-ul.
Un 403 apare și când un token care nu este token de owner trimite header-ul LanaChat-Workspace. Elimină-l.
429 rate_limited #
Fiecare token poate trimite 600 de cereri pe minut. Fiecare răspuns conține RateLimit-Remaining și RateLimit-Reset.
- Așteaptă numărul de secunde din
Retry-After, apoi încearcă din nou. - Parcurge listele cu
limit=100în loc de câte un apel pentru fiecare element. - Trimiterea mesajelor către fans este și ea limitată de restricțiile Telegram: vezi Telegram accounts and pools.
Celelalte coduri #
| Status | code | Ce să faci |
|---|---|---|
| 400 | invalid_request | Un câmp lipsește sau are format greșit: message spune care |
| 402 | insufficient_balance | Reîncarcă contul înainte de a cumpăra |
| 404 | not_found | ID-ul nu există în acest workspace: verifică că folosești token-ul corect |
| 409 | conflict | Modificarea încalcă o regulă sau un Idempotency-Key a fost refolosit cu un corp diferit |
| 500 | server_error | Încearcă din nou mai târziu cu același Idempotency-Key |
Trimite un Idempotency-Key la fiecare POST: o reîncercare nu va face lucrarea de două ori. Helper-ul din the quick start reîncearcă pentru tine 429 și 5xx.
Webhook-uri care eșuează #
O livrare este considerată eșuată când serverul tău nu răspunde cu un 2xx în 10 secunde.
- Răspunde rapid. Returnează imediat
2xx, apoi fă lucrul lent în fundal. - Verifică semnătura pe corpul brut, înainte de orice parsare JSON. Un corp parsate și re-serializat nu se potrivește niciodată.
- Verifică ceasul serverului tău. Un timestamp mai vechi de 5 minute este refuzat de codul exemplu, deci un ceas care merge greșit respinge fiecare livrare.
- Acceptă ambele valori
v1în timpul rotației secretului. - Testează cu
POST /webhooks/{id}/test(Planned), care trimite unping, și retrimite o livrare cu/deliveries/{delivery_id}/retry(Planned) după ce ai rezolvat problema.
Livrările eșuate sunt reîncercate de 8 ori pe parcursul a aproximativ 24 de ore. După 3 zile de eșecuri endpoint-ul este pus pe pauză; reia-l cu PATCH /webhooks/{id} (Planned). Același eveniment poate ajunge de două ori: ignoră duplicatele după id. Vezi Webhooks.
Încă blocat? #
Deschide bula de ajutor din dreapta jos a Consolei și scrie echipei cu endpoint-ul, statusul, code și ora apelului. Nu lipi niciodată token-ul. Vezi Get help.