--- title: Грешки и лимити description: "Справочник: HTTP кодове (4xx и 5xx), форма на пакета грешки, дневни лимити за безплатното ниво и експоненциално изчакване при 429." canonical: "https://www.tracepass.eu/bg/docs/errors" locale: bg source: "https://www.tracepass.eu/bg/docs/errors" --- # Грешки и лимити > Справочник: HTTP кодове (4xx и 5xx), форма на пакета грешки, дневни лимити за безплатното ниво и експоненциално изчакване при 429. Всеки отговор за грешка носи един и същ JSON envelope, HTTP статус кодът съответства на семантиката, а низът на грешката е достатъчно стабилен, за да превключвате по него в клиента. Списъкът по-долу е изчерпателен — ако срещнете нещо извън него, докладвайте го на [support@tracepass.eu](mailto:support@tracepass.eu). ## Envelope ```json { "error": "Validation error", "details": { "fieldErrors": { "model": ["Required"] } } } ``` `error` винаги присъства и е стабилен низ — превключвайте по него в клиента. `details` е незадължително; когато присъства, формата му зависи от конкретната грешка (flattened Zod резултат при валидация, числови данни за плана / използването при overage, име на ролята / разрешението при 403). ## Статус кодове | Статус | Кога | Повторение? | | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | | 400 | Валидационна грешка — тялото или query параметрите не преминаха schema проверка; или непознат ключ на поле при PATCH на паспорт. | Не (поправете заявката) | | 401 | Липсващ или отзован API ключ, или изтекла сесия. | Не (генерирайте нов ключ / преминете отново auth) | | 402 | DPP квотата е изчерпана при повикване за създаване на паспорт. Повторете с \`confirmOverage: true\`, ако планът поддържа overage. Връща се и когато се изисква активен абонамент, но е past\_due/canceled. | Да, с \`confirmOverage: true\` | | 403 | Plan-gate (напр. v1 API на план Free) или отказано разрешение в работното пространство. | Не | | 404 | Ресурсът не съществува или е в друго работно пространство. | Не | | 409 | Конфликт — дублиран model на продукт, GTIN регистриран от друг тенант, колизия на сериен номер в рамките на GTIN. | Понякога (разрешете конфликта, после повторете) | | 410 | Ресурсът е премахнат за постоянно (рядко; основно при публични URL на паспорти след архивиране). | Не | | 413 | Payload-ът е твърде голям — отнася се за multipart качване на изображения (5 MB лимит). | Не | | 415 | Неподдържан media type — качено изображение, което не е PNG / JPG / WebP. | Не | | 422 | Idempotency-Key е използван повторно с различно тяло на заявката. | Не (генерирайте нов ключ) | | 423 | Ресурсът е спрян (само в публичния преглед на паспорта). | Не | | 429 | Превишен лимит — дневни записи или дневни четения на паспорти. | Да (след следващата UTC полунощ) | | 500 | Необработена грешка на сървъра. Алармирани сме. | Да (с backoff) | | 503 | Maintenance прозорец или претоварване. Връща Retry-After. | Да (след Retry-After) | ## Насоки за повторение За редовете „Да“ по-горе: експоненциален backoff с jitter, ограничен до шест опита. Не приемаме повторения, по-агресивни от веднъж в секунда на един endpoint — нещо по-бързо няма да достигне базата данни (in-memory rate limiter ги отхвърля), но ще изгори дневния ви бюджет за запис.`Retry-After` header се задава при всеки `503`; нулирането на rate-limit за `429` винаги е следващата 00:00 UTC. **Tip —** Свържете всяко повторение със същия `Idempotency-Key` като оригинала — така избягвате двойно създаване на паспорт, когато оригиналното записване е успяло, но отговорът е изгубен. ## Често срещани низове на грешки | Низ на грешката | Статус | Значение | | --------------------------------------------------------------------------------------------------------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | Validation error | 400 | Schema проверката е неуспешна. details.fieldErrors носи причините по поле (Zod flatten()). | | Invalid field key: | 400 | PATCH .../fields/ е цитирал ключ, който не е в шаблона на паспорта. | | No template found for category: | 400 | Категорията, която сте изпратили, не е seeded — проверете изписването спрямо публичния Buyer's Guide. | | A product with this model already exists for your company | 409 | Низовете model са уникални в работното пространство. Изберете различен model или актуализирайте съществуващия продукт. | | This GTIN is already registered by another company. Contact support if this is an error. | 409 | GTIN е глобално уникален между тенантите — две компании не могат да притежават един и същ GTIN. | | Serial number already exists for this GTIN | 409 | Изберете различен сериен номер. В рамките на един GTIN серийните номера трябва да са уникални. | | Idempotency-Key has already been used with a different request body. Use a new key for the new request, or reuse the original body. | 422 | Изпратили сте същия ключ два пъти с различни тела. Генерирайте нов ключ. | | overage\_required | 402 | DPP квотата е изчерпана. Тялото носи planLimit + currentUsage + extraPriceCents. Повторете с \`confirmOverage: true\`, за да приемете таксата за паспорт. | | API rate limit: N writes/day via /api/v1\. Currently X today; requested Y. Retry tomorrow (UTC) or upgrade your plan. | 429 | Дневният v1 бюджет за запис е изчерпан. Изчакайте или направете upgrade. | | API rate limit: N passports/day read via /api/v1\. Currently X today; requested Y. Retry tomorrow (UTC) or contact support for a bulk export. | 429 | Дневният v1 бюджет за четене на паспорти е изчерпан. Изчакайте, направете upgrade, или използвайте JSON-LD масовия експорт от таблото. | | Passport not found | 404 | Грешен ID или грешно работно пространство. Проверете, че API ключът съответства на работното пространство, което притежава паспорта. | Не променяме формулировката на низ на грешка в minor версия. Ако ни трябва по-ясен низ, добавяме sibling `code` поле в envelope-а (числово, namespaced) и го обявяваме в регулаторния changelog. Стабилните низове ви позволяват да превключвате уверено.