Кодове за грешки

Разбиране на API отговорите при грешка и как да ги обработвате.

Преглед

API-то връща стандартизирани отговори при грешка със специфични кодове на грешка, за да ви помогне да идентифицирате и разрешите проблемите бързо.

Формат на отговор при грешка

Всички отговори при грешка следват тази структура:

{
  "status": "error",
  "error": {
    "code": "AUTH_1001",
    "message": "Missing authentication credentials",
    "details": "Both 'username' and 'password' fields are required",
    "timestamp": "2025-12-22T10:30:00Z"
  }
}

Поле	Тип	Описание
`status`	string	Винаги "error" за отговори при грешка
`error.code`	string	Уникален идентификатор на грешката
`error.message`	string	Четимо съобщение за грешката
`error.details`	string	Допълнителен контекст (по избор)
`error.timestamp`	string	ISO 8601 времеви печат

Грешки при удостоверяване (1000-1099)

Грешки, свързани с удостоверителните данни и удостоверяването.

Код	HTTP	Съобщение	Решение
`AUTH_1001`	401	Липсващи удостоверителни данни	Включете както потребителско име, така и парола в заявката
`AUTH_1002`	401	Невалидно потребителско име или парола	Проверете дали удостоверителните данни са правилни
`AUTH_1003`	403	Акаунтът е временно заключен	Изчакайте преди да опитате отново или се свържете с поддръжката

Грешки на квотата (1100-1199)

Грешки, свързани с API квотата и лимитите на заявките.

Код	HTTP	Съобщение	Решение
`QUOTA_1101`	403	Недостатъчна API квота	Закупете повече кредити или проверете квотата
`QUOTA_1102`	429	API квотата е превишена	Изчакайте за нулиране на квотата или надстройте плана

Грешки при валидация (2000-2099)

Грешки, свързани с валидацията на заявките и входните данни.

Код	HTTP	Съобщение	Решение
`VAL_2001`	400	Не е качен файл	Включете файл в заявката
`VAL_2002`	400	Невалиден формат на файла	Използвайте поддържани формати: PDF, PNG, JPG, WEBP
`VAL_2003`	400	Не са разрешени няколко PDF файла	Качете един PDF или няколко изображения
`VAL_2004`	400	PDF и изображения не могат да се смесват	Качете или PDF, или изображения, не и двете
`VAL_2005`	400	Неподдържан езиков код	Използвайте поддържан езиков код

Грешки при обработка (3000-3099)

Грешки по време на обработката на документа и AI анализа.

Код	HTTP	Съобщение	Решение
`PROC_3001`	500	Обработката на документа е неуспешна	Проверете качеството на изображението, опитайте отново
`PROC_3002`	500	Извличането на метаданните е неуспешно	Уверете се, че документът съдържа четим текст
`PROC_3003`	500	Извличането на параметри е неуспешно	Проверете дали форматът на кръвния тест е разпознаваем
`PROC_3004`	500	Генерирането на интерпретация е неуспешно	Опитайте отново
`PROC_3006`	504	Изтичане на времето за обработка	Намалете размера на файла или разделете на няколко заявки
`PROC_3007`	500	Анализът е неуспешен след повторни опити	Изчакайте и опитайте отново или се свържете с поддръжката

Сървърни грешки (5000-5099)

Вътрешни сървърни грешки и проблеми с наличността на услугата.

Код	HTTP	Съобщение	Решение
`SRV_5001`	500	Вътрешна сървърна грешка	Опитайте заявката отново, свържете се с поддръжката, ако е постоянна
`SRV_5002`	503	Услугата е временно недостъпна	Изчакайте и опитайте отново с експоненциално забавяне

Най-добри практики за обработка на грешки

Препоръки

Винаги проверявайте полето status — Успешните отговори имат "status": "success"
Реализирайте логика за повторен опит за временни грешки (5xx) с експоненциално забавяне
Записвайте кодовете на грешки за отстраняване на грешки и мониторинг
Показвайте потребителски приятелски съобщения въз основа на кодовете на грешки
Използвайте sandbox крайни точки за тестване на обработката на грешки

Пример за обработка на грешки (JavaScript)

async function analyzeBloodTest(file) {
  try {
    const response = await fetch(API_URL, {
      method: 'POST',
      body: formData
    });

    const data = await response.json();

    if (data.status === 'error') {
      const errorCode = data.error.code;

      switch (true) {
        case errorCode.startsWith('AUTH_'):
          throw new Error('Удостоверяването е неуспешно. Моля, проверете удостоверителните данни.');
        case errorCode.startsWith('QUOTA_'):
          throw new Error('Квотата е превишена. Моля, надстройте плана си.');
        case errorCode.startsWith('VAL_'):
          throw new Error('Невалидна заявка: ' + data.error.message);
        case errorCode.startsWith('PROC_'):
          // Повторен опит за грешки при обработка
          return retryRequest(file);
        default:
          throw new Error('Възникна грешка. Моля, опитайте отново.');
      }
    }

    return data.data;
  } catch (error) {
    console.error('API грешка:', error);
    throw error;
  }
}