Referință erori

Toate erorile API qr3.app respectă RFC 7807 Problem Details cu Content-Type: application/problem+json.

{
  "type": "https://docs.qr3.app/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "QR code qr_xxx not found"
}

`errors/validation`

HTTP 422 Unprocessable Entity

Datele de intrare nu au trecut de validarea schemei. Răspunsul conține un tablou errors cu detalii specifice fiecărui câmp.

{
  "type": "https://docs.qr3.app/errors/validation",
  "title": "Validation Error",
  "status": 422,
  "detail": "Request body validation failed",
  "errors": [
    { "field": "url", "message": "Invalid URL format" }
  ]
}

Cauze: Câmpuri obligatorii lipsă, tipuri de date incorecte, valori în afara intervalului permis, format URL nevalid.

`errors/bad-request`

HTTP 400 Bad Request

Corpul cererii nu este un JSON valid, deși Content-Type: application/json este setat (de exemplu, o virgulă după ultimul element, un corp trunchiat sau un corp gol).

`errors/authentication`

HTTP 401 Unauthorized

Cheia API lipsește, are un format incorect, este expirată sau a fost revocată.

Rezolvare: Verifică dacă antetul Authorization: Bearer qr3_sk_... este prezent și dacă cheia este activă.

`errors/unauthorized`

HTTP 401 Unauthorized

Un webhook de intrare (POST /v1/webhooks/clerk, POST /v1/webhooks/eu-registry) a fost apelat fără o semnătură sau un secret valid. O cheie API lipsă sau nevalidă răspunde în schimb cu errors/authentication.

`errors/authorization`

HTTP 403 Forbidden

Cheia API este validă, dar nu are scope-ul necesar sau permisiunea necesară.

`errors/forbidden`

HTTP 403 Forbidden

Resursa există, dar aparține unui alt Workspace sau unei alte organizații.

`errors/document-immutable`

HTTP 403 Forbidden

Un document DPP încărcat cu is_immutable nu poate fi șters.

`errors/not-found`

HTTP 404 Not Found

Resursa solicitată nu există sau a fost ștearsă.

`errors/conflict`

HTTP 409 Conflict

O resursă cu același identificator unic există deja (de exemplu, slug duplicat sau coliziune Idempotency-Key).

`errors/subscription-exists`

HTTP 409 Conflict

POST /v1/billing/checkout a fost apelat deși organizația are deja un abonament. Schimbă mai degrabă planul în portalul de facturare.

`errors/rate-limited`

HTTP 429 Too Many Requests

Limita de rată pe minut a cheii API a fost depășită. Răspunsul conține antetele Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining și X-RateLimit-Reset.

`errors/rate-limit`

HTTP 429 Too Many Requests

O limită de rată specifică resursei a fost depășită (de exemplu, 200 de coduri QR pe zi per Workspace).

`errors/plan-limit`

HTTP 422 Unprocessable Entity

Planul tău curent nu permite această acțiune (de exemplu, cota de DPP-uri sau de coduri dinamice a fost epuizată, lotul este prea mare, prea multe spații de lucru sau membri ai echipei). Este necesar un upgrade.

`errors/invalid-file-type`

HTTP 400 Bad Request

Fișierul încărcat are un tip pe care endpoint-ul nu îl acceptă, sau conținutul său nu corespunde valorii Content-Type declarate.

`errors/file-too-large`

HTTP 413 Payload Too Large

Fișierul încărcat depășește limita de dimensiune a planului sau a endpoint-ului.

`errors/storage-limit-exceeded`

HTTP 422 Unprocessable Entity

Încărcarea ar depăși spațiul total de stocare al spațiului de lucru sau al DPP.

`errors/not-configured`

HTTP 503 Service Unavailable

Un serviciu necesar sau o configurație lipsește (de exemplu, Stripe nu este configurat, cheia API Web Risk nu este setată).

`errors/unsafe-url`

HTTP 422 Unprocessable Entity

Adresa URL a fost respinsă deoarece a fost clasificată ca nesigură de Google Web Risk (malware, phishing, inginerie socială).

`errors/url-flagged`

HTTP 422 Unprocessable Entity

Rezervat pentru URL-uri care au fost clasificate ulterior ca nesigure în timpul scanării periodice (re-scanare).

`errors/already-submitted`

HTTP 409 Conflict

Trimitere duplicată — de exemplu, a fost trimis deja un scor NPS pentru acest Workspace în această lună.

`errors/unprocessable-entity`

HTTP 422 Unprocessable Entity

O acțiune de admin nu este permisă (de exemplu, impersonarea unui alt superadmin). Doar endpoint-urile de superadmin returnează acest tip.

`errors/request-error`

HTTP 4xx Client Error

Tip de rezervă pentru erorile de client care nu au un tip mai specific; statusul se află în răspuns. API-ul nu are în prezent nicio cale cunoscută care să îl returneze.

`errors/internal`

HTTP 500 Internal Server Error

O eroare neașteptată pe server. Te rugăm să reîncerci cererea. În caz de probleme persistente: [email protected].