Справка за грешки

Всички грешки на qr3.app API следват RFC 7807 Problem Details с 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

Входните данни не преминаха валидацията на схемата. Отговорът съдържа масив errors с детайли за конкретните полета.

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

Причини: Липсващи задължителни полета, неправилни типове данни, стойности извън разрешения диапазон, невалиден формат на URL.

`errors/authentication`

HTTP 401 Unauthorized

API ключът липсва, е с неправилен формат, изтекъл е или е анулиран.

Решение: Проверете дали заглавната част Authorization: Bearer qr3_sk_... присъства и дали ключът е активен.

`errors/authorization`

HTTP 403 Forbidden

API ключът е валиден, но няма необходимия обхват (scope) или разрешение.

`errors/forbidden`

HTTP 403 Forbidden

Ресурсът съществува, но принадлежи на друго работно пространство (Workspace) или друга организация.

`errors/not-found`

HTTP 404 Not Found

Заявеният ресурс не съществува или е бил изтрит.

`errors/conflict`

HTTP 409 Conflict

Ресурс със същия уникален идентификатор вече съществува (напр. дублиран slug или колизия на Idempotency-Key).

`errors/rate-limited`

HTTP 429 Too Many Requests

Лимитът на заявките (Rate-Limit) за минута за този API ключ е надвишен. Отговорът съдържа заглавните части Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset.

`errors/rate-limit`

HTTP 429 Too Many Requests

Надвишен е специфичен за ресурса лимит на заявките (напр. 200 QR кода на ден за работно пространство).

`errors/plan-limit`

HTTP 429 Too Many Requests

Текущият план не позволява това действие (напр. твърде много работни пространства). Изисква се надграждане.

`errors/not-configured`

HTTP 503 Service Unavailable

Липсва необходима услуга или конфигурация (напр. Stripe не е конфигуриран, API ключът за Web Risk не е зададен).

`errors/unsafe-url`

HTTP 422 Unprocessable Entity

URL адресът беше отхвърлен, тъй като е класифициран като опасен от Google Web Risk (зловреден софтуер, фишинг, социално инженерство).

`errors/url-flagged`

HTTP 422 Unprocessable Entity

Резервирано за URL адреси, които впоследствие са били класифицирани като опасни при периодичното повторно сканиране.

`errors/already-submitted`

HTTP 409 Conflict

Дублирано изпращане — напр. вече е изпратен NPS резултат за това работно пространство за този месец.

`errors/internal`

HTTP 500 Internal Server Error

Възникна неочаквана грешка на сървъра. Моля, опитайте заявката отново. При постоянни проблеми: [email protected].