Ошибки

Каждая ошибка — это JSON-объект со стабильным машиночитаемым code, человекочитаемым сообщением и идентификатором запроса. Сопоставляйте по code, а не по тексту сообщения или одному лишь HTTP-статусу.

Конверт ошибки

ответ с ошибкой

{
  "error": {
    "type": "invalid_request_error",
    "code": "stream_not_found",
    "message": "No stream with id cBczepiZSW8GJaCae0xIj7 in this project.",
    "request_id": "req_0Kj2wq8ULn4mAe1s",
    "doc_url": "https://runnev.dev/docs/errors#stream_not_found"
  }
}

doc_url указывает на закреплённую запись для этого кода на этой странице.

Типы ошибок

type	HTTP	Значение
`authentication_error`	401, 403	Ключ отсутствует, недействителен, отозван или здесь не разрешён.
`invalid_request_error`	400, 404, 409, 413, 415, 422	Запрос некорректен или ссылается на несуществующее.
`rate_limit_error`	429	Вы превысили лимит частоты или объёма. Отступите.
`api_error`	500, 503	Что-то сломалось на нашей стороне. Повторите с backoff.

Коды

code	HTTP	Причина	Средство устранения
`missing_api_key`	401	Нет заголовка Authorization.	Отправьте `Authorization: Bearer ...`.
`invalid_api_key`	401	Ключ некорректен или неизвестен.	Проверьте значение и префикс ключа.
`key_revoked`	401	Ключ был отозван.	Выпустите новый ключ.
`project_forbidden`	403	Ключ принадлежит другому проекту.	Используйте ключ этого проекта.
`stream_not_found`	404	Нет такого потока в этом проекте.	Проверьте id.
`stream_name_taken`	409	Переданный id уже существует.	Используйте новый id или опустите его.
`invalid_stream_id`	400	Id не является base62-идентификатором.	Используйте 22-символьную строку base62.
`invalid_sequence`	409	Иные байты для существующего номера.	Не переписывайте историю; используйте следующий номер.
`sequence_too_far_ahead`	422	seq > cursor + 1024.	Публикуйте непрерывные номера.
`payload_too_large`	413	Тело больше 8 МиБ.	Разбейте по номерам.
`unsupported_media_type`	415	Content-type тела не разрешён для режима потока.	JSON для потоков json, octet-stream для raw.
`retention_out_of_range`	422	retention_seconds вне 60–2592000.	Выберите значение в диапазоне.
`stream_limit_reached`	403	Достигнута квота потоков проекта.	Удалите поток или повысьте тариф.
`rate_limited`	429	Превышен лимит частоты или пропускной способности.	Соблюдайте `retry-after`; отступите.
`internal_error`	500	Неожиданный сбой сервера.	Повторите с backoff; напишите в поддержку с id запроса.
`upstream_unavailable`	503	Зависимость временно недоступна.	Повторите с backoff.

Идентификаторы запроса

Каждый ответ, успешный или с ошибкой, включает x-request-id в заголовках, а тела ошибок повторяют его как request_id. Когда что-то идёт не так, зафиксируйте его и приведите дословно в поддержку; это позволяет нам найти точный запрос в логах без игры в угадайку. SDK отдают его в каждом объекте ошибки.

Справочник по кодам

Полное JSON-тело для каждого кода, с якорями, чтобы ссылки doc_url попадали сюда.

missing_api_key

401

{"error":{"type":"authentication_error","code":"missing_api_key","message":"No API key was provided. Send it as: Authorization: Bearer rnv_live_...","request_id":"req_0Kj2wq8ULn4mAe1s","doc_url":"https://runnev.dev/docs/errors#missing_api_key"}}

invalid_api_key

401

{"error":{"type":"authentication_error","code":"invalid_api_key","message":"The API key is malformed or does not exist.","request_id":"req_7Za1popL2mn4Ae0s","doc_url":"https://runnev.dev/docs/errors#invalid_api_key"}}

key_revoked

401

{"error":{"type":"authentication_error","code":"key_revoked","message":"This API key has been revoked.","request_id":"req_2Bc3de4FGhi5Jk6l","doc_url":"https://runnev.dev/docs/errors#key_revoked"}}

project_forbidden

403

{"error":{"type":"authentication_error","code":"project_forbidden","message":"This key cannot access streams in another project.","request_id":"req_Q3ee1l0Pmn4bAe2s","doc_url":"https://runnev.dev/docs/errors#project_forbidden"}}

stream_not_found

404

{"error":{"type":"invalid_request_error","code":"stream_not_found","message":"No stream with id cBczepiZSW8GJaCae0xIj7 in this project.","request_id":"req_0Kj2wq8ULn4mAe1s","doc_url":"https://runnev.dev/docs/errors#stream_not_found"}}

stream_name_taken

409

{"error":{"type":"invalid_request_error","code":"stream_name_taken","message":"A stream with the supplied id already exists.","request_id":"req_8Uv9wx0YZab1Cd2e","doc_url":"https://runnev.dev/docs/errors#stream_name_taken"}}

invalid_stream_id

400

{"error":{"type":"invalid_request_error","code":"invalid_stream_id","message":"Stream id must be a 22-character base62 string.","request_id":"req_3Fg4hi5JKlm6No7p","doc_url":"https://runnev.dev/docs/errors#invalid_stream_id"}}

invalid_sequence

409

{"error":{"type":"invalid_request_error","code":"invalid_sequence","message":"seq 41823 already exists with different content.","request_id":"req_9Wx0yz1ABcd2Ef3g","doc_url":"https://runnev.dev/docs/errors#invalid_sequence"}}

sequence_too_far_ahead

422

{"error":{"type":"invalid_request_error","code":"sequence_too_far_ahead","message":"seq 45000 is more than 1024 ahead of the current cursor 41823.","request_id":"req_1Ab2cd3EFgh4Ij5k","doc_url":"https://runnev.dev/docs/errors#sequence_too_far_ahead"}}

payload_too_large

413

{"error":{"type":"invalid_request_error","code":"payload_too_large","message":"Publish body is 10.4 MiB; the limit is 8 MiB. Split it across sequences.","request_id":"req_5Mn6op7QRst8Uv9w","doc_url":"https://runnev.dev/docs/errors#payload_too_large"}}

unsupported_media_type

415

{"error":{"type":"invalid_request_error","code":"unsupported_media_type","message":"This stream is json mode; send application/json, not application/octet-stream.","request_id":"req_4Hi5jk6LMno7Pq8r","doc_url":"https://runnev.dev/docs/errors#unsupported_media_type"}}

retention_out_of_range

422

{"error":{"type":"invalid_request_error","code":"retention_out_of_range","message":"retention_seconds must be between 60 and 2592000.","request_id":"req_6Op7qr8STuv9Wx0y","doc_url":"https://runnev.dev/docs/errors#retention_out_of_range"}}

stream_limit_reached

403

{"error":{"type":"invalid_request_error","code":"stream_limit_reached","message":"This project has reached its stream limit. Delete a stream or upgrade.","request_id":"req_0Yz1ab2CDef3Gh4i","doc_url":"https://runnev.dev/docs/errors#stream_limit_reached"}}

rate_limited

429

{"error":{"type":"rate_limit_error","code":"rate_limited","message":"Rate limit exceeded. Retry after 2s.","request_id":"req_2Cd3ef4GHij5Kl6m","doc_url":"https://runnev.dev/docs/errors#rate_limited"}}

internal_error

500

{"error":{"type":"api_error","code":"internal_error","message":"An unexpected error occurred. Quote the request id to support.","request_id":"req_7Kl8mn9OPqr0St1u","doc_url":"https://runnev.dev/docs/errors#internal_error"}}

upstream_unavailable

503

{"error":{"type":"api_error","code":"upstream_unavailable","message":"A dependency is temporarily unavailable. Retry with backoff.","request_id":"req_3De4fg5HIjk6Lm7n","doc_url":"https://runnev.dev/docs/errors#upstream_unavailable"}}