Reference

shredstream.sh error code reference

Interpret account API codes, uncoded HTTP failures, verification failures, and receiver-local UDP and shred conditions with a concrete remediation for each.

Response shape

Current account API failures represented by a service error use a JSON object with error and code fields plus the HTTP status shown below. An unexpected server failure returns HTTP 500 with a generic error message and no documented code field.

UDP has no response channel. The live stream does not emit service error records. Receiver failures therefore appear as missing traffic, kernel counters, parser rejections, or application metrics.

Account API codes

Code	HTTP status	Condition	Meaning	Remediation
bad_email	400	Email is absent, not text, malformed, or longer than accepted by the application	The sign-in request cannot identify a valid email input	Submit the email address used for purchase in normal address form
bad_code	400	Code record is absent, expired, over its attempt allowance, incorrect, or not tied to an account	Authentication failed without disclosing which check failed	Request a new sign-in code and enter the newest code once
unauthenticated	401	Session cookie is absent or invalid on a protected destination route	The request has no accepted account session	Sign in again, preserve the secure cookie, and repeat the request
no_token	400	Verification token is empty	The verify route has no challenge proof to submit	Read the newest UDP challenge and submit its nonempty token within 600 seconds
bad_destination	400	Destination address or port fails current application validation	The requested receive tuple is not accepted	Use a public IPv4 destination and an accepted UDP port, then retry
at_cap	409	Account already has five destinations	The customer destination cap is reached	Reuse or remove an existing destination; do not create a sixth
no_free_slot	402	Every paid connection is already assigned to a destination	No purchased destination slot is available	Purchase another connection or free a currently assigned slot
slot_race	409	Another request claimed the selected paid slot first	Concurrent account activity won the allocation race	Reload current account state and submit once against a free slot
rate_limited	429	An account, email, or client address exceeded a route attempt allowance	Abuse protection refused the request temporarily	Stop retries, wait several minutes, and resume with bounded pacing
email_unavailable	502	The email provider did not accept a sign-in or contact message	The application could not send the message	Retry after a short delay; contact the service if repeated attempts fail
service_not_configured	503	A required server configuration value is unavailable	Account access is temporarily unavailable	Retry later; do not change receiver configuration in response
fanout_unreachable	503	The account application could not reach the delivery service	Delivery control is unavailable, but the request did not change the account	Preserve current state and retry later
fanout_error	Upstream status	The delivery service returned a non-success response	The message and status originate from the delivery control request	Follow the returned message; retry only when the status and operation make retry safe
fulfillment_update_failed	502	Checkout completion could not be reported back to checkout	Provisioning may have succeeded while the checkout message update failed	Check the account before paying again, then contact the service with the checkout reference
service_error	Varies	A ServiceError is constructed without a more specific code	Generic service failure category	Use the HTTP status and error message; preserve the request identifier if available

The login-session status endpoint can return HTTP 401 with signedIn false and no code field. Treat that as an unauthenticated session condition, not as a malformed JSON response.

Uncoded HTTP conditions

HTTP result	Code field	Meaning	Remediation
401 with signedIn false	Absent	No valid login session on the session-status check	Request a new sign-in code
500 with generic error text	Absent	An unhandled server failure was hidden to avoid leaking internals	Retry once with the same safe request, then report time and route
Non-JSON network failure	Not available	DNS, TLS, routing, proxy, timeout, or connection failure occurred before a valid response	Record the client error and test the network path separately
Request aborted by client	Not available	Caller canceled before completion	Determine whether the operation can be repeated without duplicating intent

Verification and delivery conditions

The labels in this table are a recommended receiver vocabulary. They are not datagrams returned by shredstream.sh.

Local condition	Detection	Meaning	Remediation
challenge_timeout	No challenge before the 600-second token window closes	Verification path did not complete in time	Bind first, allow 64.130.40.90, capture the destination port, then request a new challenge
challenge_prefix_mismatch	Datagram does not begin with SHRED-FANOUT-VERIFY/1	Traffic is not in the documented challenge form	Reject it, retain a bounded sample, and verify the source
challenge_source_mismatch	Challenge-like datagram comes from another IP	Packet is outside the documented source contract	Reject it and keep the allowlist at 64.130.40.90/32
live_stream_absent	Verified receiver observes no live datagrams	Activation delay, routing, firewall, NAT, socket, or service state may be responsible	Compare source-filtered packet capture with socket and account state
unexpected_source	Live datagram source is not 64.130.40.90	Packet is outside the documented service contract	Count separately and do not enter trusted parsing
wrong_destination	Packet reaches another address or port	Dashboard tuple, NAT mapping, or socket binding differs	Compare the registered pair at every boundary
source_port_assumption	Firewall permits only a captured source UDP port	An undocumented source-port constraint blocks traffic	Remove the source-port condition
firewall_drop	Edge or host rule counter rises for the feed tuple	An admission layer rejected the datagram	Permit UDP from 64.130.40.90/32 to the configured port
conntrack_drop	Conntrack insert, drop, or table-full counter rises	Stateful processing refused or lost the flow	Fix table pressure or bypass conntrack for a safe non-NAT feed tuple
reverse_path_drop	Traffic disappears on a multihomed or asymmetric host with reverse filtering	Reverse route does not satisfy the configured rp_filter mode	Correct routing or select loose filtering where policy permits
no_listener	UdpNoPorts rises for the destination	No socket was bound when the datagram arrived	Start and bind the receiver before verification and streaming

Datagram and kernel conditions

Local condition	Detection	Meaning	Remediation
oversize_datagram	Received UDP payload exceeds 1,228 bytes	Packet violates the product maximum	Reject before parsing and retain a bounded sample
msg_trunc	Receive flags include MSG_TRUNC	Application buffer was smaller than the datagram	Allocate at least 1,228 bytes per receive slot and reject truncated bytes
ancillary_truncated	Receive flags include MSG_CTRUNC	Timestamp or drop-counter control data was cut off	Increase control-buffer space and invalidate affected measurements
nic_drop	Driver or interface receive-discard delta rises	Packet was lost before normal stack delivery	Fix ring depth, queue placement, interrupt service, or upstream link errors
softnet_drop	The softnet input-backlog drop field rises	Per-CPU network backlog overflowed	Fix CPU placement or processing capacity; test netdev backlog changes
softnet_time_squeeze	The softnet budget-exhaustion field rises	NAPI or softirq work exceeded its cycle budget	Measure budget and CPU-affinity changes with application latency
socket_overflow	UdpRcvbufErrors or per-socket drops rises	UDP receive memory filled before user space drained it	Increase drain capacity and test a measured SO_RCVBUF request
application_queue_full	Bounded handoff rejects an item	Decoder or consumer cannot keep pace with ingest	Move work off ingest, add capacity, or apply a protocol-aware shedding policy
stale_packet	Queue residence exceeds the stated freshness budget	Buffering preserved bytes after their useful time	Invalidate affected state under the receiver’s age policy

Shred parser and validator conditions

Local condition	Detection	Meaning	Remediation
short_common_header	Datagram is shorter than 83 bytes	Common fields cannot be read safely	Reject before any offset access
unsupported_variant	Variant discriminator is unknown to the pinned parser	Receiver does not support the packet format	Upgrade from an authoritative release and retain a diagnostic sample
wrong_shred_version	Header version differs from trusted cluster configuration	Packet belongs to another lineage or configuration is stale	Verify the target cluster and expected value
impossible_data_size	Data size is below 88 or beyond variant or receive bounds	Declared ledger-data boundary is invalid	Reject before exposing data bytes
invalid_parent_offset	Offset implies an impossible parent relationship	Data header is malformed or outside accepted slot rules	Reject and record slot plus offset
invalid_flags	Data flag combination contains unsupported state	Completion or reference-tick interpretation is unsafe	Reject under the pinned bit definition
invalid_coding_counts	k or m is zero, impossible, or conflicts with set members	Recovery dimensions are invalid	Reject the member and preserve existing consistent state
invalid_coding_position	position is not less than m	Coding member has no legal local shard position	Reject before recovery allocation
index_underflow	Derived first coding index or FEC relation underflows	Index metadata is inconsistent	Reject and avoid unsigned wraparound
leader_unknown	Trusted schedule has no leader key for the slot context	Authentication cannot be completed	Load authoritative schedule context before admission
bad_legacy_signature	Legacy signed-data verification fails	Scheduled leader did not authenticate the packet	Reject and count by source, slot, and leader
bad_merkle_proof	Proof cannot reconstruct a valid root for the shard position	Merkle membership is invalid	Reject the member and do not place it in FEC state
bad_leader_signature	Leader signature does not verify over the variant-defined message	Origin authentication failed	Reject and preserve bounded conflict evidence
bad_retransmitter_signature	Extra retransmitter evidence fails its rule	Retransmission authentication is invalid	Reject or isolate according to the pinned variant rules
duplicate	Identical canonical bytes arrive for the same identity	A repeated copy was received	Keep the earliest valid copy and increment duplicate count
duplicate_conflict	Different canonical bytes claim the same identity	Equivocation, corruption, or parser-context conflict exists	Keep both as evidence, stop silent overwrite, and verify authentication

Recovery, ordering, and decode conditions

Local condition	Detection	Meaning	Remediation
fec_metadata_conflict	Members of one FEC key disagree on counts, size, variant, root, or version	Shards cannot enter one Reed-Solomon matrix safely	Split only by valid context or reject the conflicting member
incomplete_fec_set	Fewer than k compatible shards arrive before closeout	Missing data cannot yet be reconstructed	Wait inside policy, use another source, or mark the range unavailable
fec_recovery_failed	Reed-Solomon reconstruction fails with apparently sufficient members	One or more members or dimensions are wrong	Revalidate every shard and discard corrupted state
recovered_shred_invalid	A reconstructed data shred fails sanitation or authentication	Mathematical output is not acceptable protocol data	Reject the recovered member and mark the set failed
out_of_order	Valid identity arrives behind a later data index	UDP or path reordered packets	Buffer inside a bounded slot-aware window
data_gap	A required data index remains absent and unrecovered	Ordered ledger bytes are incomplete	Do not decode across the gap
premature_slot_end	Last-in-slot appears while earlier required data is absent	Completion marker does not make the range complete	Continue recovery or close the slot as incomplete
entry_decode_failed	Contiguous bytes do not decode into valid entries	Boundary, recovery, version, or data integrity is wrong	Stop at the last valid boundary and inspect source shreds
transaction_decode_failed	Entry transaction bytes do not match a supported message form	Decoder or bytes are incompatible	Pin the matching Solana transaction decoder and retain the entry
address_lookup_missing	Version 0 transaction references unavailable table state	Loaded account keys cannot be resolved	Fetch or maintain the correct lookup-table state for that slot
clock_invalid	Clock step, missing timestamp, wrong domain, or uncertainty exceeds policy	Latency sample cannot support a timing claim	Exclude the affected interval and repair clock discipline

Logging rule

Aggregate high-rate conditions by code, source, slot range, variant, and time window. Keep bounded packet samples for structural failures and duplicate conflicts. Do not write one log line per invalid packet at feed rate because logging can create the next receive overflow.

Questions

Does the UDP stream send error messages?: No. UDP delivery has no response channel and the documented live payload is a raw Solana shred, not a service envelope. Delivery failures appear as missing packets, network counters, socket drops, parser rejections, or stale application state. The receiver-local labels on this page provide a consistent diagnostic vocabulary.
What should an integrator do with fanout_error?: Read both the returned HTTP status and error message because fanout_error represents a non-success response passed through from delivery control. Do not assume every instance is retryable. Preserve current account state, avoid duplicate mutations, and retry only when the status, message, and operation make repetition safe.
Why are duplicate and duplicate_conflict separate?: An identical duplicate is expected in multi-path or repeated delivery and can be reduced to the earliest valid copy. A conflicting duplicate carries different bytes under the same cluster, slot, shred type, and index. Silent overwrite would destroy evidence of corruption, context error, or authenticated equivocation.