# Обработка ошибок

## Единый формат ответа об ошибке

Все ошибки API возвращают единый формат JSON:

```json
{
  "code": 2010,
  "message": "Insufficient credits",
  "suggestion": "Please top up your account at https://platform.tripo3d.ai",
  "request_id": "req_abc123"
}
```

| Поле | Тип | Описание |
| :-: | :-: | :-: |
| code | целое число | Код ошибки |
| message | строка | Описание ошибки |
| suggestion | строка | Предлагаемое исправление |
| request_id | строка | Уникальный идентификатор запроса для устранения неполадок |

## HTTP Коды состояния

| Код состояния | Значение | Описание |
| :-: | :-: | :-: |
| 200 | Успех | Запрос успешно обработан |
| 400 | Неверные параметры | Обязательные параметры отсутствуют или имеют неправильный формат. |
| 401 | Неаутентифицированный | API Key отсутствует или недействителен. |
| 403 | Недостаточно разрешений | У вас нет разрешения на доступ к ресурсу или ваших кредитов недостаточно. |
| 404 | Ресурс не найден | Запрошенная задача или ресурс не существует. |
| 429 | Слишком много запросов | Превышен лимит скорости. Уменьшите частоту запросов |
| 500 | Ошибка сервиса | Внутренняя ошибка сервера. Повторите попытку позже |

## Ссылка на код ошибки

| Код ошибки | Значение | Рекомендуемое обращение |
| :-: | :-: | :-: |
| 1000 | Неверный API Key | Проверьте, правильный ли API Key или он был удален. |
| 1001 | Несанкционированный | Проверьте, содержит ли заголовок запроса `Authorization`. |
| 2000 | Превышен лимит скорости | Уменьшите частоту запросов и реализуйте повторные попытки с экспоненциальной задержкой. |
| 2002 | Неподдерживаемый параметр запроса | Проверьте, соответствуют ли имена и значения полей тела запроса документации. |
| 2003 | Пустой входной файл | Убедитесь, что загруженный файл не пуст и имеет допустимый формат. |
| 2004 | Неподдерживаемый тип файла | Проверьте, находится ли формат файла в списке поддерживаемых |
| 2008 | Нарушение политики в отношении контента | Измените входной контент, чтобы избежать запрещенных слов или изображений. |
| 2010 | Недостаточно кредитов | Пополнение кредитов в консоли |
| 2015 | Версия устарела | Обновите до последней версии API. |
| 2018 | Модель слишком сложная | Уменьшите сложность или количество полигонов входной модели. |

## Примеры обработки ошибок

### Python

```python
import time
import requests

def call_api_with_retry(url, headers, payload=None, max_retries=3):
    for attempt in range(max_retries):
        if payload:
            response = requests.post(url, headers=headers, json=payload)
        else:
            response = requests.get(url, headers=headers)

        if response.status_code == 200:
            return response.json()

        if response.status_code == 429:
            wait = 2 ** attempt
            print(f"Rate limit triggered. Retrying in {wait} seconds...")
            time.sleep(wait)
            continue

        error = response.json()
        raise Exception(
            f"API error [{error['code']}]: {error['message']} "
            f"(suggestion: {error.get('suggestion', 'none')})"
        )

    raise Exception("Maximum retry attempts exhausted")
```

### JavaScript

```javascript
async function callApiWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.ok) {
      return await response.json();
    }

    if (response.status === 429) {
      const wait = 2 ** attempt * 1000;
      console.log(`Rate limit triggered. Retrying in ${wait / 1000} seconds...`);
      await new Promise(resolve => setTimeout(resolve, wait));
      continue;
    }

    const error = await response.json();
    throw new Error(
      `API error [${error.code}]: ${error.message} (suggestion: ${error.suggestion || "none"})`
    );
  }

  throw new Error("Maximum retry attempts exhausted");
}
```

## Рекомендации по стратегии повторной попытки

Для повторяющихся ошибок, таких как 429 ограничений скорости и 500 ошибок обслуживания, используйте экспоненциальную стратегию отсрочки:

1. Первая повторная попытка: подождите 1 секунду.
2. Вторая повторная попытка: подождите 2 секунды.
3. Третья повторная попытка: подождите 4 секунды.
4. Сохраняйте максимальное количество повторов на уровне 5 или меньше.

Для неповторяемых ошибок, таких как 400, 401 и 403, создайте исключение напрямую и устраните основную проблему.