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

Всички грешки на 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/bad-request`

HTTP 400 Bad Request

Тялото не е валиден JSON, въпреки че е зададен Content-Type: application/json (напр. запетая след последния елемент, отрязано или празно тяло).

`errors/authentication`

HTTP 401 Unauthorized

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

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

`errors/unauthorized`

HTTP 401 Unauthorized

Входящ webhook (POST /v1/webhooks/clerk, POST /v1/webhooks/eu-registry) е извикан без валиден подпис или тайна. При липсващ или невалиден API ключ се връща errors/authentication вместо това.

`errors/authorization`

HTTP 403 Forbidden

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

`errors/forbidden`

HTTP 403 Forbidden

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

`errors/document-immutable`

HTTP 403 Forbidden

DPP документ, качен с is_immutable, не може да бъде изтрит.

`errors/not-found`

HTTP 404 Not Found

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

`errors/conflict`

HTTP 409 Conflict

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

`errors/subscription-exists`

HTTP 409 Conflict

Извикан е POST /v1/billing/checkout, въпреки че организацията вече има абонамент. Променете плана в портала за таксуване вместо това.

`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 422 Unprocessable Entity

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

`errors/invalid-file-type`

HTTP 400 Bad Request

Каченият файл е от тип, който крайната точка не приема, или съдържанието му не съответства на декларирания Content-Type.

`errors/file-too-large`

HTTP 413 Payload Too Large

Каченият файл надвишава лимита за размер на плана или на крайната точка.

`errors/storage-limit-exceeded`

HTTP 422 Unprocessable Entity

Качването би надвишило общото пространство за съхранение на работното пространство (workspace) или на DPP.

`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/unprocessable-entity`

HTTP 422 Unprocessable Entity

Администраторско действие не е разрешено (напр. имитиране на друг superadmin). Само крайните точки за superadmin връщат този тип.

`errors/request-error`

HTTP 4xx Client Error

Резервен тип за клиентски грешки без по-конкретен тип; статусът се намира в отговора. В момента API няма известен път, който да го връща.

`errors/internal`

HTTP 500 Internal Server Error

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