Ошибки и устранение неполадок

Копировать

• Копировать для LLM

  Копировать страницу как Markdown для LLM
• Просмотреть как Markdown

  Открыть эту страницу как Markdown
• Открыть в ChatGPT

  Получить анализ от ChatGPT
• Открыть в Claude

  Получить инсайты от Claude
• Подключиться к Cursor

  Установить сервер MCP в Cursor
• Подключиться к VS Code

  Установить сервер MCP в VS Code

Все ошибки Vilna API соответствуют формату RFC 7807 Problem Details и возвращаются как application/problem+json.

Формат ошибок

Каждый ответ об ошибке содержит как минимум поля type, title и status:

{
  "type": "https://docs.vilna.io/apis/problems/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Address not found"
}

Ошибки валидации

Запросы, не прошедшие валидацию входных данных, возвращают статус 400 с массивом fields, описывающим каждое невалидное поле:

{
  "type": "https://docs.vilna.io/apis/problems/invalid-request",
  "title": "Invalid Request",
  "status": 400,
  "detail": "Validation error",
  "fields": [
    { "name": "value", "reason": "must not be empty" },
    { "name": "chainFamily", "reason": "must be one of: evm, bitcoin, solana, tron" }
  ]
}

Типы ошибок

Ограничение частоты запросов

При превышении лимита запросов API возвращает 429 со стандартным телом ошибки:

{
  "type": "https://docs.vilna.io/apis/problems/rate-limit",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded"
}

Каждый ответ содержит заголовки с информацией о лимитах:

При получении 429 дождитесь момента X-RateLimit-Reset перед повторной попыткой. Если заголовок недоступен, используйте экспоненциальную задержку с джиттером.

Серверные ошибки и повторные попытки

Ошибки 5xx указывают на временную проблему на стороне сервера. Повторяйте запросы с экспоненциальной задержкой: 1с, 2с, 4с и далее до максимума 30с, не более 5 попыток. Добавляйте случайный джиттер (например, 0-500мс) к каждой задержке, чтобы избежать эффекта «громового стада».

Идемпотентность: запросы GET и DELETE безопасны для повторной отправки. Запросы POST, PUT и PATCH могут быть неидемпотентными — проверьте документацию эндпоинта или используйте ключ идемпотентности, если он поддерживается.

Обработка ошибок с помощью SDK

SDK возвращает { data, error } из каждого вызова. Проверяйте error перед использованием data:

const { data, error } = await client.POST("/addresses/external", {
  body: {
    value: "0x...",
    chainFamily: "evm",
    label: "Treasury",
  },
});

if (error) {
  switch (error.status) {
    case 400:
      // Ошибка валидации - проверьте отдельные поля
      for (const field of error.fields ?? []) {
        console.error(`${field.name}: ${field.reason}`);
      }
      break;

    case 404:
      console.error("Resource not found:", error.detail);
      break;

    case 409:
      console.error("Conflict:", error.detail);
      break;

    default:
      console.error(`${error.title}: ${error.detail}`);
  }
}

Обработка ошибок с помощью curl

curl -s -w "\n%{http_code}" "https://${VILNA_NAMESPACE}.vilna.app/addresses/invalid" \
  -H "X-Api-Key: your-api-key" | jq .

Ответ 404 выглядит так:

{
  "type": "https://docs.vilna.io/apis/problems/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Address not found"
}

Типичные проблемы и решения

Недействительный API-ключ

Ошибка: 401 Unauthorized

Убедитесь, что заголовок X-Api-Key присутствует и ключ активен. Ключи привязаны к пространству имён — проверьте, что вы обращаетесь к правильному базовому URL (https://{namespace}.vilna.app).

Адрес не найден

Ошибка: 404 Not Found

Проверьте, что формат адреса соответствует сети. EVM-адреса начинаются с 0x и содержат 42 символа. TRON-адреса начинаются с T и содержат 34 символа. Адрес должен быть предварительно зарегистрирован через API.

Сеть не активна

Ошибка: 422 Unprocessable Entity

Перед мониторингом адресов в блокчейне сначала активируйте его:

curl -X POST "https://${VILNA_NAMESPACE}.vilna.app/blockchains/eip155:137/actions/activate" \
  -H "X-Api-Key: your-api-key"

Сбой доставки вебхука

Ошибка: Канал помечен как неработающий после повторных сбоев доставки

• Убедитесь, что URL вебхука публично доступен из интернета.
• Убедитесь, что эндпоинт возвращает HTTP 2xx в течение 10 секунд.
• Проверьте, что эндпоинт принимает Content-Type: application/json.

Ошибки формата CAIP

Vilna использует стандарты CAIP для идентификаторов сетей, аккаунтов и активов.

Типичные ошибки:

• Использование числового идентификатора сети вместо формата CAIP-2 (1 вместо eip155:1)
• Отсутствие префикса пространства имён в идентификаторах активов

Дополнительные материалы