Отладка API: чек-лист поиска и исправления ошибок

Введение

Каждый разработчик тратит часы на отладку API. Запрос не проходит, ответ приходит не тот, ошибка непонятная — знакомо? Разница между джуниором и сеньором часто в том, как быстро разработчик находит и исправляет проблему.

Эта статья — ваш систематический чек-лист отладки API. Не хаотичное «ну попробуй ещё раз», а пошаговый алгоритм: от первой ошибки до её решения. С инструментами, примерами кода и реальными кейсами.

Вы научитесь:

• ✅ Быстро классифицировать ошибку по HTTP-статусу
• ✅ Использовать правильные инструменты (curl, Postman, DevTools, прокси)
• ✅ Отлаживать CORS, аутентификацию, таймауты и SSL
• ✅ Читать и анализировать логи
• ✅ Строить воспроизводимые тест-кейсы

Алгоритм отладки: 7 шагов

Когда API-запрос не работает, следуйте этому алгоритму — от общего к частному:

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Field 'email' must be a valid email address",
    "field": "email",
    "details": "Got value: 'not-an-email'"
  }
}

curl -v -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"name": "Иван", "email": "ivan@test.ru"}'

Ошибки 4xx: проблемы на стороне клиента

# Проверьте JSON через jq
echo '{"name": "Иван", "age": 30}' | jq .

# Частая ошибка — забыли Content-Type
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Иван"}'

# Проверьте JWT
echo "YOUR_JWT_TOKEN" | cut -d'.' -f2 | base64 -d 2>/dev/null | jq .
# Смотрите поле "exp" — Unix timestamp истечения

# Тестируйте с токеном
curl -v https://api.example.com/me \
  -H "Authorization: Bearer eyJhbGci..."

# Частые причины 404:
/api/users/    ← trailing slash может менять роут
/api/Users     ← регистр имеет значение
/api/v1/users  ← старая версия API
/api/user      ← единственное число вместо множественного

// Типичный ответ 422
{
  "errors": {
    "email": ["The email has already been taken."],
    "age": ["The age must be at least 18."],
    "name": ["The name field is required."]
  }
}

// Обработка 429 с retry
async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || 1;
      console.warn(`Rate limited. Retry after ${retryAfter}s`);
      await new Promise(r => setTimeout(r, retryAfter * 1000));
      continue;
    }

    return response;
  }
  throw new Error('Max retries exceeded');
}

Ошибки 5xx: проблемы на стороне сервера

Сетевые ошибки

Когда запрос не доходит до сервера — статус кода нет, в браузере ERR_...:

# Проверить SSL-сертификат
openssl s_client -connect api.example.com:443 -servername api.example.com 2>/dev/null | openssl x509 -noout -dates
# notBefore=Feb 1 00:00:00 2026 GMT
# notAfter=Feb 1 00:00:00 2027 GMT

# Диагностика: ping + traceroute
ping -c 3 api.example.com
traceroute api.example.com

# curl с таймаутом
curl --connect-timeout 5 --max-time 10 https://api.example.com/health

CORS: отдельная головная боль

CORS (Cross-Origin Resource Sharing) — механизм браузера, блокирующий кросс-доменные запросы. Если вы видите в консоли:

Access to fetch at 'https://api.example.com' from origin 'http://localhost:3000'
has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present.

Как отлаживать CORS

1. Откройте DevTools → Network

   Найдите запрос. Если есть предварительный OPTIONS-запрос (preflight) — посмотрите его ответ:

   HTTP/1.1 200 OK
   Access-Control-Allow-Origin: http://localhost:3000
   Access-Control-Allow-Methods: GET, POST, PUT, DELETE
   Access-Control-Allow-Headers: Content-Type, Authorization
   Access-Control-Max-Age: 86400

2. Проверьте, отправляет ли сервер заголовки

   # Отправьте OPTIONS-запрос вручную
   curl -v -X OPTIONS https://api.example.com/users \
     -H "Origin: http://localhost:3000" \
     -H "Access-Control-Request-Method: POST" \
     -H "Access-Control-Request-Headers: Content-Type, Authorization"
   
   # Ищите в ответе: Access-Control-Allow-*

3. Настройте сервер — добавьте CORS-заголовки. Подробнее — в нашей статье «5 способов исправить CORS-ошибку».

Инструменты отладки

curl: швейцарский нож

curl — универсальный инструмент для отладки API из терминала. Полезные флаги:

# Полная информация: заголовки запроса и ответа
curl -v https://api.example.com/users

# Только заголовки ответа
curl -I https://api.example.com/users

# POST с JSON-телом
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{"name": "Иван", "email": "ivan@test.ru"}'

# Вывести тело ответа + HTTP-статус
curl -s -o /dev/null -w "%{http_code}" https://api.example.com/health

# Таймаут подключения и ожидания
curl --connect-timeout 5 --max-time 30 https://api.example.com/slow-endpoint

# Следовать редиректам
curl -L https://api.example.com/redirect

# Игнорировать SSL (для тестирования с самоподписанным сертификатом)
curl -k https://localhost:8443/api

# Замер времени
curl -o /dev/null -s -w "
  DNS:        %{time_namelookup}s
  Connect:    %{time_connect}s
  TLS:        %{time_appconnect}s
  FirstByte:  %{time_starttransfer}s
  Total:      %{time_total}s
  HTTP Code:  %{http_code}
" https://api.example.com/users

* Connected to api.example.com (93.184.216.34) port 443
> POST /users HTTP/2               ← ваш запрос (>)
> Host: api.example.com
> Authorization: Bearer eyJhbG...
> Content-Type: application/json
>
< HTTP/2 201                        ← ответ сервера (<)
< content-type: application/json
< x-request-id: req_abc123
<
{"id": 42, "name": "Иван"}         ← тело ответа

Логирование запросов

Добавьте логирование в ваш код — это сэкономит часы отладки:

JavaScript (Axios interceptors)

import axios from 'axios';

const api = axios.create({ baseURL: 'https://api.example.com' });

// Логирование запросов
api.interceptors.request.use(config => {
  console.log(`→ ${config.method.toUpperCase()} ${config.url}`, {
    headers: config.headers,
    data: config.data
  });
  config.metadata = { startTime: Date.now() };
  return config;
});

// Логирование ответов
api.interceptors.response.use(
  response => {
    const duration = Date.now() - response.config.metadata.startTime;
    console.log(`← ${response.status} ${response.config.url} (${duration}ms)`, {
      data: response.data
    });
    return response;
  },
  error => {
    const duration = Date.now() - error.config.metadata.startTime;
    console.error(`✕ ${error.response?.status || 'NETWORK'} ${error.config.url} (${duration}ms)`, {
      data: error.response?.data,
      message: error.message
    });
    return Promise.reject(error);
  }
);

Python (requests + logging)

import requests
import logging
import time

logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger('api')

class APIClient:
    def __init__(self, base_url, token):
        self.base_url = base_url
        self.session = requests.Session()
        self.session.headers.update({
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        })

    def request(self, method, path, **kwargs):
        url = f'{self.base_url}{path}'
        logger.info(f'→ {method} {url}')
        if 'json' in kwargs:
            logger.debug(f'  Body: {kwargs["json"]}')

        start = time.time()
        try:
            response = self.session.request(method, url, **kwargs)
            duration = (time.time() - start) * 1000
            logger.info(f'← {response.status_code} {url} ({duration:.0f}ms)')

            if not response.ok:
                logger.error(f'  Error: {response.text}')

            response.raise_for_status()
            return response.json()
        except requests.exceptions.ConnectionError as e:
            logger.error(f'✕ Connection failed: {e}')
            raise

PHP (Guzzle middleware)

<?php

use GuzzleHttp\Client;
use GuzzleHttp\Middleware;
use GuzzleHttp\MessageFormatter;
use Monolog\Logger;
use Monolog\Handler\StreamHandler;

$logger = new Logger('api');
$logger->pushHandler(new StreamHandler('php://stderr', Logger::DEBUG));

$stack = \GuzzleHttp\HandlerStack::create();
$stack->push(
    Middleware::log(
        $logger,
        new MessageFormatter(
            "→ {method} {uri}\n← {code} ({res_header_Content-Type})\n{res_body}"
        )
    )
);

$client = new Client([
    'base_uri' => 'https://api.example.com',
    'handler' => $stack,
    'timeout' => 10,
    'headers' => [
        'Authorization' => 'Bearer ' . $token,
        'Content-Type' => 'application/json'
    ]
]);

Финальный чек-лист

FAQ

Заключение

Систематический подход к отладке превращает часы мучений в минуты диагностики. Сохраните этот чек-лист — он пригодится при следующей API-ошибке (а она обязательно будет).

Статья опубликована: 23 февраля 2026
Автор: LightBox API Team