Всеки отговор за грешка носи един и същ JSON envelope, HTTP статус кодът съответства на семантиката, а низът на грешката е достатъчно стабилен, за да превключвате по него в клиента. Докладвайте неочаквани статус кодове на support@tracepass.eu.
Envelope
json
{
"error": "Validation error",
"details": {
"fieldErrors": {
"model": ["Required"]
}
}
}error винаги присъства и е стабилен низ — превключвайте по него в клиента. details е незадължително; когато присъства, формата му зависи от конкретната грешка (съобщения по поле в fieldErrors при валидация, числови данни за плана / използването при overage, име на ролята / разрешението при 403).
Статус кодове
| Статус | Кога | Повторение? |
|---|---|---|
| 400 | Валидационна грешка — тялото или query параметрите не преминаха schema проверка; или непознат ключ на поле при PATCH на паспорт. | Не (поправете заявката) |
| 401 | Липсващ или отзован API ключ, или изтекла сесия. | Не (генерирайте нов ключ / преминете отново auth) |
| 402 | Надхвърлен лимит на плана, когато планът има тарифа за overage: `epcis_events_overage_required` при EPCIS capture, `measurements_overage_required` при измервания. При Free EPCIS capture и измерванията връщат вместо това `epcis_events_hard_block` / `measurements_hard_block`. Създаването на паспорт никога не връща 402 заради лимита на плана: черновата не заема място от плана, а лимитът се прилага при публикуване от таблото. Връща се и от v1 записите, които добавят или променят съдържание, когато плащанията не са редовни (просрочени, неплатени или абонаментът е анулиран). Четенето продължава да работи, както и проверките на обхвата, докладите за грешен отговор, проверките на каталога и промените в профила за съответствие. | Overage: да, с `confirmOverage: true`. Твърд лимит: не (upgrade). Плащания: не (първо уредете плащането) |
| 403 | Отказано разрешение в работното пространство (напр. само-доставчически пълномощия, опитващи се да извършат v1 запис). | Не |
| 404 | Ресурсът не съществува или е в друго работно пространство. | Не |
| 409 | Конфликт. При запис на паспорт: паспортът е архивиран (`passport_archived`); идентификационно поле (GTIN, сериен номер и др.) е заключено след първото публикуване (`identifier_locked`, с имената на заключените полета в `keys`); или надпревара за паралелен запис (`concurrent_update` — заредете отново и опитайте пак). При всеки v1 запис: заявка със същия Idempotency-Key все още се обработва (`idempotency_key_in_use` — повторете със същия ключ, след като приключи). При създаване на продукт или паспорт: дублиран model, GTIN регистриран от друг тенант, или колизия на сериен номер в рамките на GTIN. | За concurrent_update и idempotency_key_in_use: да (повторете). Останалите: първо разрешете конфликта |
| 410 | Паспортът е изтекъл: абонаментът е приключил и 30-дневният гратисен период е изтекъл. Той отново става достъпен, ако абонаментът бъде възстановен. Архивираните паспорти връщат 404, не 410. | Не |
| 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, ограничен до шест опита. Агресивните повторения изгарят дневния ви бюджет за запис без полза. Retry-After header се задава при всеки 503; нулирането на rate-limit за 429 винаги е следващата 00:00 UTC.
Често срещани низове на грешки
| Низ на грешката | Статус | Значение |
|---|---|---|
Validation error | 400 | Schema проверката е неуспешна. details.fieldErrors съдържа причините, групирани по поле. |
Invalid field key: <key> | 400 | PATCH .../fields/<key> е цитирал ключ, който не е в шаблона на паспорта. |
No template found for category: <slug> | 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 серийните номера трябва да са уникални. |
passport_archived | 409 | Паспортът е архивиран. Архивираните паспорти са постоянно само за четене. Паспорт, маркиран за изтриване, също е само за четене и връща същия код. |
identifier_locked | 409 | Заявката би променила, изчистила или отменила одобрението на идентификационно поле (напр. gtin, serialNumber), което вече притежава одобрена стойност в публикуван паспорт. Стойност, която все още чака преглед, може да се коригира, а празно поле – да се попълни. Масивът keys изброява заключените полета. |
concurrent_update | 409 | Друг запис промени паспорта, докато тази промяна се записваше. Заредете паспорта отново и опитайте пак. |
idempotency_key_in_use | 409 | Заявка със същия Idempotency-Key все още се обработва. Изчакайте я да приключи и повторете със същия ключ: ще получите нейния резултат. |
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 | Изпратили сте същия ключ два пъти с различни тела. Генерирайте нов ключ. |
Subscription is past due — resolve billing to continue creating new content. Published passports remain accessible. | 402 | Плащанията не са редовни. Записите, които добавят или променят съдържание, се отказват; всяко четене продължава да работи, а публикуваните паспорти остават достъпни. Уредете плащането от таблото. |
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 ключът съответства на работното пространство, което притежава паспорта. |