Обработка ошибок и повторов

Формат ошибкиСкопировать ссылку

Любая ошибка API возвращается как application/problem+json (RFC 9457), полностью — ниже весь набор полей, а не только самые полезные:

{
  "type": "https://docs.typizer.ru/errors/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "detail": "schema: total is required",
  "code": "invalid_request",
  "param": "schema",
  "request_id": "req_…",
  "doc_url": "https://docs.typizer.ru/errors/invalid_request"
}

• code — машиночитаемый код (см. таблицу ниже и «Коды ошибок»);
• type и doc_url — одна и та же ссылка на страницу этого кода, https://docs.typizer.ru/errors/<code>; открывайте её прямо из кода, если нужно разобраться в причине;
• title/status — короткое название и HTTP-статус (по-английски, как того требует RFC 9457); detail — человекочитаемое описание конкретного случая (может быть на английском же, если не задано точнее);
• param, если есть, — какое поле запроса виновато;
• request_id — приложите его в обращение в поддержку (support@typizer.ru), если ошибка кажется внутренней.

Что стоит повторятьСкопировать ссылку

Полная таблица со статусами HTTP — «Коды ошибок». При сетевой ошибке без ответа (таймаут, обрыв соединения) безопасно повторить запрос с тем же Idempotency-Key — см. ниже.

Idempotency-Key: безопасные повторыСкопировать ссылку

Заголовок Idempotency-Key — ваш собственный идентификатор запроса (1–255 печатных ASCII-символов, например uuid4), который делает повтор безопасным:

• повтор с тем же ключом и тем же телом запроса в течение 24 часов возвращает результат первого запроса (с заголовком Idempotent-Replayed: true), ничего не создавая и не тарифицируя повторно;
• тот же ключ, тем же телом, но исходный запрос ещё обрабатывается — тоже 409 idempotency_conflict, но временно: повторите чуть позже с тем же ключом, когда исходный запрос завершится, ответ станет обычным повтором-replay;
• тот же ключ с другим телом запроса — тоже 409 idempotency_conflict, но уже не временно: заведите новый ключ для этого, другого запроса, повтор с тем же ключом ошибку не исправит;
• если резервирование страниц под запрос не удалось (402 или иная ошибка до создания ресурса), ключ освобождается — его можно использовать повторно для следующей попытки того же запроса;
• на демонстрационных прогонах (POST /v1/demo/runs) и согласиях (consents) заголовок принимается, но игнорируется — там нет риска двойного списания.

Отправляйте Idempotency-Key на:

• POST /v1/extract;
• POST /v1/typizers/{id}/runs;
• POST /v1/batches;
• POST /v1/runs/{id}/retry.

В MCP у инструмента extract то же назначение выполняет аргумент idempotency_key — подробнее в справочнике MCP.

Плановые работыСкопировать ссылку

Во время объявленного или идущего технического обслуживания (и 24 часа до его начала) ответы /v1/* и /mcp несут заголовок Typizer-Maintenance: <mnt_id>; starts=<ISO-время>; ends=<ISO-время>. GET /v1/status отдаёт список текущих и ещё не завершённых запланированных событий — это не история прошедших работ, а то, что идёт или только предстоит. Публичная страница состояния сервиса появится на status.typizer.ru позже; Typizer-Maintenance и GET /v1/status доступны уже сейчас и не требуют авторизации.

Что дальшеСкопировать ссылку

• «Коды ошибок» — полная таблица с HTTP-статусами.
• «Лимиты» — заголовки RateLimit-* и Retry-After.
• «Приём вебхуков» — асинхронные ошибки доставки.