Грешки и лимити

Всеки отговор за грешка носи един и същ JSON envelope, HTTP статус кодът съответства на семантиката, а низът на грешката е достатъчно стабилен, за да превключвате по него в клиента. Списъкът по-долу е изчерпателен — ако срещнете нещо извън него, докладвайте го на support@tracepass.eu.

Envelope

{
  "error": "Validation error",
  "details": {
    "fieldErrors": {
      "model": ["Required"]
    }
  }
}

error винаги присъства и е стабилен низ — превключвайте по него в клиента. details е незадължително; когато присъства, формата му зависи от конкретната грешка (flattened Zod резултат при валидация, числови данни за плана / използването при overage, име на ролята / разрешението при 403).

Статус кодове

Насоки за повторение

За редовете „Да“ по-горе: експоненциален backoff с jitter, капнат на шест опита. Не приемаме повторения, по-агресивни от веднъж в секунда на един endpoint — нещо по-бързо няма да достигне базата данни (in-memory rate limiter ги отхвърля), но ще изгори дневния ви бюджет за запис.Retry-After header се задава при всеки 503; нулирането на rate-limit за 429 винаги е следващата 00:00 UTC.

Често срещани низове на грешки