Ошибки

Любая ошибка на любом эндпоинте использует один конверт:

{
  "error": {
    "code": "not_found",
    "message": "Link not found",
    "doc_url": "https://linkprofit.com/docs/api/errors"
  }
}

Ветвитесь по error.code, а error.message показывайте людям. Ошибки валидации добавляют массив details с сообщениями по каждому полю:

{
  "error": {
    "code": "validation_failed",
    "message": "Request failed validation",
    "doc_url": "https://linkprofit.com/docs/api/errors",
    "details": [
      { "path": "url", "message": "Destination URL is not a valid address" }
    ]
  }
}

Коды ошибок

| Код | HTTP | Значение | Что делать | |---|---|---|---| | unauthorized | 401 | Ключ отсутствует, неизвестен, отозван или истёк | Проверьте заголовок; выпустите новый ключ | | forbidden | 403 | Неподходящий вид ключа для эндпоинта или операция не разрешена | Используйте ключ рабочего пространства / партнёрский, как описано | | insufficient_scope | 403 | У ключа нет требуемой области действия | Создайте ключ с областью, названной в сообщении | | plan_restricted | 403 | Тариф не включает эту возможность | Повысьте тариф или уберите функцию из запроса | | not_found | 404 | Ресурс не существует — или принадлежит другому арендатору | Проверьте идентификатор; чужие ресурсы неотличимы от отсутствующих | | invalid_request | 400 | Некорректный JSON, плохой курсор, нарушенное бизнес-правило | Исправьте запрос | | validation_failed | 422 | Тело или строка запроса не прошли проверку по схеме | Исправьте поля, перечисленные в details | | conflict | 409 | Конфликт состояния: занятый slug, повторный Idempotency-Key с другим телом | Выберите другое значение или новый ключ идемпотентности | | quota_exceeded | 422 | Квота тарифа исчерпана (ссылки, домены, клиенты) | Повысьте тариф или освободите квоту | | rate_limited | 429 | Слишком много запросов для этого ключа | Подождите Retry-After секунд; см. лимиты частоты | | not_configured | 503 | Возможность не настроена в этом окружении | Повторите позже или обратитесь в поддержку | | internal | 500/502/504 | Непредвиденная ошибка платформы | Повторите с отступом; сообщите нам, если повторяется | | invalid_click_id | 422 | click_id подделан, изменён или выдан в другом рабочем пространстве | Передавайте значение параметра с идентификатором клика ровно таким, каким оно пришло в адресе назначения | | attribution_expired | 422 | Клик старше окна атрибуции рабочего пространства | Повторять нечего; при необходимости измените окно в панели |

Правила обработки, которые окупаются

• 404 — это ещё и изоляция. Идентификатор из другого рабочего пространства отвечает not_found, но никогда forbidden: API не раскрывает, существует ли чужой идентификатор.
• Повторяйте только то, что безопасно. Повторяйте internal и rate_limited с отступом. Никогда не повторяйте вслепую conflict или validation_failed — сам запрос неверен. Чтобы повторы изменяющих запросов были безопасны, используйте Idempotency-Key.
• GET /links никогда не отдаёт 404. Пустые фильтры возвращают пустой список; 404 на коллекции был бы неоднозначен.