Интеграция с Pinterest API v5 через протокол OAuth 2.0 — стандартный способ получения доступа к данным пользователей от их имени. Однако этап обмена кода авторизации (authorization_code) на токен доступа (access_token) часто становится источником трудностей для разработчиков. В этой статье мы подробно разберем наиболее частые ошибки, возникающие при запросе к эндпоинту https://api.pinterest.com/v5/oauth/token, их причины и способы устранения на актуальную дату .

Базовый поток OAuth 2.0 в Pinterest: Краткое напоминание

Прежде чем разбирать ошибки, важно убедиться, что последовательность действий верна:

1. Перенаправление пользователя на https://www.pinterest.com/oauth/ с параметрами client_id, redirect_uri, response_type=code, scope и state.
2. Пользователь авторизуется и дает согласие на разрешения.
3. Pinterest перенаправляет обратно на ваш redirect_uri с параметром code (код авторизации) и state.
4. Ваш бэкенд отправляет POST-запрос на https://api.pinterest.com/v5/oauth/token с grant_type=authorization_code, code, redirect_uri, client_id и client_secret.
5. Получение ответа с access_token, refresh_token и сроком действия.

Критически важно: Код авторизации (code) одноразовый и имеет короткое время жизни (обычно несколько минут). Любая попытка повторного использования или задержка приведет к ошибке.

Топ-5 ошибок при обмене кода на токен и их решения

Ошибка «Invalid authorization code» (Неверный код авторизации)

Это самая частая ошибка. В предоставленных данных из сообщества разработчиков (community.pinterest.biz) пользователь digitalfuelshiny столкнулся с тем, что код, полученный «мгновенно перед использованием», оказался недействительным («the auth code was bad»); Проблема решилась получением нового кода авторизации.

Причины:

• Код уже использован: Код одноразовый. Если вы тестировали запрос в Postman/cURL, а потом запустили код приложения — код уже сгорел.
• Истек срок действия: Задержка между получением редиректа и отправкой POST-запроса.
• Ошибка копирования: Потеря символов, перенос строки или лишние пробелы при ручном копировании.
• Несовпадение redirect_uri: URI в запросе токена должен в точности совпадать с тем, что был в запросе авторизации (включая слеш в конце, http/https, порт).

Решение:

1. Инициируйте полностью новый цикл авторизации (шаг 1).
2. Автоматизируйте обмен кода на токен на бэкенде сразу после получения редиректа, исключая ручные действия.
3. Логируйте полученный code и отправляемый redirect_uri для сверки.

Ошибка «Redirect URI mismatch» (Несоответствие URI перенаправления)

Pinterest строго валидирует redirect_uri. Даже минимальное расхождение вызовет ошибку 400 Bad Request с описанием invalid_grant или redirect_uri_mismatch.

Чек-лист проверки:

• В настройках приложения (Pinterest Developer Portal) добавлен точный URI.
• В запросе авторизации (/oauth/) и в запросе токена (/v5/oauth/token) передан идентичный URI.
• Проверьте протокол: https обязателен для продакшена (localhost часто допускает http, но лучше использовать https через туннели вроде ngrok).
• Проверьте слеш в конце: https://example.com/callback != https://example.com/callback/.

Ошибка «Invalid client» / «Unauthorized» (Неверные учетные данные клиента)

Происходит при неверном client_id или client_secret.

Способы передачи секрета (Client Secret):

Pinterest API v5 поддерживает два способа аутентификации клиента при обмене кода:

1. Basic Auth (Рекомендуемый): Заголовок Authorization: Basic base64(client_id:client_secret). Тело запроса: grant_type=authorization_code&code=...&redirect_uri=....
2. В теле запроса (Form Data): Параметры client_id и client_secret передаются в теле application/x-www-form-urlencoded.

Совет: Используйте Basic Auth. Это безопаснее (секрет не светится в логах тела запроса) и соответствует RFC 6749. Убедитесь, что вы не передаете секрет и в заголовке, и в теле одновременно.

Ошибка «Unsupported grant type» или «Invalid request»

Часто возникает из-за неверного заголовка Content-Type или формата тела запроса.

Требования к POST-запросу на /v5/oauth/token:

• Headers: Content-Type: application/x-www-form-urlencoded (если секрет в теле) или Authorization: Basic ... + Content-Type: application/x-www-form-urlencoded.
• Body (Form Data):
  • grant_type=authorization_code (обязательно, точно так написано).
  • code=ВАШ_КОД.
  • redirect_uri=ВАШ_URI (обязательно, если использовался при авторизации).

Отправка JSON (application/json) вместо form-urlencoded приведет к ошибке парсинга.

Проблемы с Scope (Областью доступа)

Если вы запрашиваете токен для скоупов, которые не были одобрены пользователем на экране согласия (или не добавлены в настройки приложения), Pinterest может вернуть ошибку или выдать токен с ограниченными правами.

• Параметр scope в запросе авторизации должен совпадать с настроенными в Developer Portal.
• На 2026 год актуальны скоупы: boards:read, pins:read, user_accounts:read и др. Проверьте официальную документацию на случай изменений.

Ошибки работы с уже полученными токенами (Контекст)

Хотя тема статьи — обмен кода, часто разработчики путают ошибки этапа обмена с ошибками использования токена; Из интернет-источников известны такие кейсы:

«Pinterest access token is invalid. Please reconnect your Pinterest account»

Эта ошибка означает, что access_token (или refresh_token) стал недействительным.

• Истек срок действия Access Token (обычно 1 час) и Refresh Token (обычно 1 год, но может быть отозван).
• Пользователь отозвал доступ в настройках Pinterest.
• Приложение удалено или приостановлено модерацией.
• Токен скомпрометирован (утечка в логах/фронтенде).

Лечение:

Не пытайтесь «починить» старый токен. Запустите повторный OAuth-флоу (Reconnect account). Используйте refresh_token для бесшовного обновления access_token до истечения его срока.

HTTP 500 Internal Server Error

Иногда Pinterest возвращает 500 на эндпоинте токена. Это ошибка на стороне сервера.

• Реализуйте экспоненциальный бэкофф (exponential backoff) с повторными попытками (retry logic).
• Проверяйте статус API на Pinterest Status Page.
• Если ошибка повторяется системно — обратитесь в поддержку через Developer Portal.

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

Pinterest Access Token Debugger

Pinterest предоставляет инструмент для проверки токенов (Token Debugger). Он позволяет узнать:

• Принадлежит ли токен вашему приложению (client_id).
• Для какого пользователя выдан токен.
• Какие скоупы (permissions) включены.
• Действителен ли токен и когда истекает.
• Версию API (должна быть v5).

Используйте его сразу после получения токена, чтобы убедиться, что обмен прошел успешно и токен имеет нужные права.

Логирование «сырых» запросов и ответов

Всегда логируйте (в безопасном виде, маскируя секреты):

• Полный URL редиректа с кодом.
• Заголовки и тело POST-запроса к /v5/oauth/token.
• Полный HTTP-ответ: статус, заголовки, тело (JSON ошибки).

Ошибки Pinterest обычно возвращаются в формате JSON RFC 6749:

{
 "error": "invalid_grant",
 "error_description": "The authorization code is invalid or has expired."
}

Чек-лист «Почему не работает обмен кодом?» (Quick Fix)

Лучшие практики для продакшена (2026)

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

• Храните access_token и refresh_token в зашифрованном виде (Encryption at rest).
• Никогда не передавайте токены на фронтенд (браузер пользователя). Обмен кодом на токен — исключительно серверная операция (Backend-for-Frontend).
• Используйте переменные окружения для client_secret.

Обработка Refresh Token Rotation

Pinterest поддерживает ротацию рефреш-токенов (при обновлении пары access/refresh может выдаваться новый refresh_token). Ваша логика обновления должна:

1. Отправлять старый refresh_token.
2. При успехе атомарно заменять старую пару на новую в БД.
3. Обрабатывать ошибку invalid_grant при рефреше как сигнал к полному ре-авторизованию пользователя.

State-параметр (CSRF Protection)

Всегда генерируйте случайный state при старте авторизации, сохраняйте в сессии пользователя и проверяйте при редиректе. Это защищает от атак подделки межсайтовых запросов (CSRF).

Ошибки на этапе обмена authorization_code на access_token в Pinterest API в 90% случаев связаны с нарушением протокола OAuth 2.0: использование сгоревшего кода, несовпадение redirect_uri, неверный формат запроса или ошибки в учетных данных клиента.