# Depanarea API: erori comune

_API · 4 min de citit · Actualizat 2026-10-23 · https://lanachat.ai/guides/ro/api-troubleshooting/_

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:

```json
{ "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:

1. Header-ul este exact `Authorization: Bearer <token>`, cu cuvântul `Bearer` și un spațiu.
2. Token-ul a fost copiat complet. Este afișat o singură dată, când îl creezi.
3. 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.
4. 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`.

1. Găsește permisiunea în coloana **Permission** a endpoint-ului.
2. În **Users › API & MCP**, apasă **Edit** pe token și bifează permisiunea.
3. 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](https://lanachat.ai/guides/ro/api-telegram-accounts/).

## 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](https://lanachat.ai/guides/ro/api-overview/) 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.

1. **Răspunde rapid.** Returnează imediat `2xx`, apoi fă lucrul lent în fundal.
2. **Verifică semnătura pe corpul brut**, înainte de orice parsare JSON. Un corp parsate și re-serializat nu se potrivește niciodată.
3. **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.
4. **Acceptă ambele valori `v1`** în timpul rotației secretului.
5. **Testează** cu `POST /webhooks/{id}/test` (Planned), care trimite un `ping`, ș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](https://lanachat.ai/guides/ro/api-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](https://lanachat.ai/guides/ro/get-help/).

## Articole conexe

- [API LanaChat: început rapid, autentificare și erori](https://lanachat.ai/guides/ro/api-overview/)
- [API: webhook-uri, evenimente și semnături](https://lanachat.ai/guides/ro/api-webhooks/)
- [API: membri ai echipei, roluri și tokenuri de acces](https://lanachat.ai/guides/ro/api-team/)
- [Rețete rapide API: copiază, lipește, rulează](https://lanachat.ai/guides/ro/api-recipes/)