Ошибки

Любая ошибка выглядит одинаково и содержит неизменный code. Обрабатывайте ошибки по коду: сообщение написано для людей, и его формулировка может меняться.

{ "error": { "code": "invalid_key", "message": "That API key does not exist." } }

Некоторые ошибки содержат, кроме этих двух, дополнительные поля: parameter - какой параметр неверен, retry_after - сколько ждать, limit и used - для исчерпанного лимита.

Все коды

Статус	Код	Когда
400	`missing_query`	`query` пуст или не передан.
400	`unknown_format`	`format` - не один из шести.
400	`unknown_column`	В `columns` указано несуществующее поле.
400	`format_not_available`	Запрошен плоский формат там, где возвращаются не строки выдачи.
400	`per_page_too_large`	`per_page` больше лимита строк вашего тарифа. Лимит указан в ошибке.
400	`invalid_json`	Тело POST-запроса - некорректный JSON.
401	`missing_key`	Нет заголовка `Authorization: Bearer`.
401	`invalid_key`	Ключ не принадлежит ни одному аккаунту.
403	`plan_required`	У аккаунта нет платного тарифа.
404	`unknown_endpoint`	Такого пути нет. Существующие перечислены в ошибке.
405	`method_not_allowed`	API только для чтения. Используйте GET или POST с телом JSON.
429	`too_many_requests`	Запросы идут чаще десяти в минуту (API и MCP вместе).
429	`quota_exceeded`	Суточный лимит поисков исчерпан.
429	`snippet_quota_exceeded`	Суточный лимит фрагментов исчерпан. Поиск без фрагментов по-прежнему работает.

Что делать в каждом случае

400 - неверен ваш запрос, и повтор не поможет. Поле parameter подскажет, что именно не так.
401, 403 - дело в ключе или тарифе. Повторять бессмысленно, пока что-то не изменится.
429 too_many_requests - подождите retry_after секунд и повторите. Ничего не израсходовано.
429 quota_exceeded - лимит восстановится в ближайшую полночь по UTC; retry_after показывает, сколько до неё осталось. Повторять раньше бесполезно.
5xx - проблема на нашей стороне. Повторяйте с растущей задержкой.

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

Ошибки приходят в JSON или в XML, если был запрошен format=xml. У плоских форматов нет способа записать ошибку, поэтому неудачный запрос, в котором был указан csv, получит JSON. Значит, клиенту, который читает CSV, нужно проверять код статуса, а не считать любое тело строками выдачи.

Коды без чтения этой страницы

GET / возвращает в JSON все перечисленные выше коды с их значением. Ключ для этого не нужен, так что клиент можно написать под полный набор кодов, ни разу не открыв браузер.

curl https://api.publicwww.com/

Далее Примеры кода