Errors

Every error is a JSON object with a stable machine-readable code, a human message, and the request id. Match on code, not on the message text or the HTTP status alone.

The error envelope

error response

{
  "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"
  }
}

The doc_url points at the anchored entry for that code on this page.

Error types

type	HTTP	Meaning
`authentication_error`	401, 403	The key is missing, invalid, revoked, or not allowed here.
`invalid_request_error`	400, 404, 409, 413, 415, 422	The request is malformed or refers to something that does not exist.
`rate_limit_error`	429	You exceeded a rate or volume limit. Back off.
`api_error`	500, 503	Something failed on our side. Retry with backoff.

Codes

code	HTTP	Cause	Remedy
`missing_api_key`	401	No Authorization header.	Send `Authorization: Bearer ...`.
`invalid_api_key`	401	Key malformed or unknown.	Check the key value and prefix.
`key_revoked`	401	Key was revoked.	Issue a new key.
`project_forbidden`	403	Key belongs to another project.	Use a key for this project.
`stream_not_found`	404	No such stream in this project.	Check the id.
`stream_name_taken`	409	Supplied id already exists.	Use a new id or omit it.
`invalid_stream_id`	400	Id is not a base62 id.	Use a 22-character base62 string.
`invalid_sequence`	409	Different bytes for an existing sequence.	Do not rewrite history; use the next sequence.
`sequence_too_far_ahead`	422	seq > cursor + 1024.	Publish contiguous sequences.
`payload_too_large`	413	Body over 8 MiB.	Split across sequences.
`unsupported_media_type`	415	Body content type not allowed for the stream mode.	Use JSON for json streams, octet-stream for raw.
`retention_out_of_range`	422	retention_seconds outside 60-2592000.	Pick a value in range.
`stream_limit_reached`	403	Project stream quota hit.	Delete a stream or upgrade the plan.
`rate_limited`	429	Rate or throughput limit exceeded.	Honour `retry-after`; back off.
`internal_error`	500	Unexpected server fault.	Retry with backoff; contact support with the request id.
`upstream_unavailable`	503	A dependency is temporarily down.	Retry with backoff.

Request ids

Every response, success or error, includes x-request-id in its headers, and error bodies repeat it as request_id. When something goes wrong, capture it and quote it verbatim to support; it lets us find the exact request in our logs without a guessing game. The SDKs expose it on every error object.

Per-code reference

The full JSON body for each code, anchored so that doc_url links land here.

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"}}