Recebi o código X, o que eu faço?
Recebi o código X, o que eu faço?
Pergunta: "recebi o código X, o que eu faço?"
Gerada do catálogo de erro (src/error-catalog.ts, ERROR_CATALOG) — não editar à mão. Rode cd packages/event-room && npm run docs:generate depois de mudar o catálogo; npm run build (no mesmo diretório) falha se este arquivo divergir da regeneração.
Como ler a tabela
Toda linha tem o remedy — a ação a tomar — ao lado do código, nunca em outra página. retryable diz se tentar de novo automaticamente faz sentido; quando não, a ação é sempre humana ou de outro tipo (reautenticar, reescanear, trocar de contrato).
Um código que não está nesta tabela é desconhecido desta versão da lib — ele ainda chega como observação não-terminal, nunca é descartado (code, known: false), mas não tem remedy específico: trate como falha de serviço genérica e considere reportar.
As quatro categorias
- usage (erro de programação — lança síncrono, antes de qualquer I/O):
access_mode_required,already_attached,contract_async_validator,contract_invalid_definition,contract_required,contract_reserved_prefix,contract_too_large,creator_required,credential_required,display_name_required,event_not_in_contract,event_payload_invalid,event_unknown_to_peer,guest_url_reserved_param,host_closed,invalid_access_mode,invalid_event,invalid_guest_url,invalid_max_guests,invalid_room_id,join_already_pending,join_code_required,malformed_join_target,not_joined,payload_too_large_client,qr_url_required,request_id_required,request_not_found,role_required,room_id_collision,room_id_generation_exhausted,room_still_open,unknown_role,unsupported_guest_url_scheme,unsupported_qr_runtime - flow (condição de jornada — rejeita a promise da chamada causadora):
creator_replaced,join_rejected,room_already_exists,room_full,too_many_code_attempts - ended (fim de sessão — estado terminal com
reason):protocol_version_mismatch - infra (falha de serviço/código desconhecido — observação não-terminal, nunca silenciada):
bad_json,bad_message,event_not_allowed,event_out_of_contract,idle_timeout,invalid_creator_token,invalid_join_code,occupancy_limit_not_honored,payload_too_large,room_not_found,room_rate_limited,service_unavailable,unknown_type
Tabela completa
| code | category | remedy | retryable |
|---|---|---|---|
access_mode_required | usage | accessMode is mandatory — there is no default in code — for both createHost and startRoom. | não |
already_attached | usage | This connection already has a room association — this library should never send a second create/join on an already-associated connection. | não |
bad_json | infra | The server could not parse a wire message as JSON. | não |
bad_message | infra | The server rejected a malformed wire message. | não |
contract_async_validator | usage | Contract validators must be synchronous — an async/Promise-returning validator was supplied. | não |
contract_invalid_definition | usage | The contract definition is not a valid shape node. | não |
contract_required | usage | send() requires a contract — pass one to createHost/joinRoom to traffic app events. | não |
contract_reserved_prefix | usage | Event names starting with the reserved protocol prefix cannot be part of an app contract. | não |
contract_too_large | usage | The contract's digest map exceeds the fingerprint budget — split or shrink the contract. | não |
creator_replaced | flow | Another connection took over as this room's creator while this specific call was in flight. | não |
creator_required | usage | Only the room's creator connection may perform this action — this library should not have offered it otherwise. | não |
credential_required | usage | credential is required — the guest/host's own logged-in session, opaque to this library. There is no "credential: none". | não |
display_name_required | usage | This accessMode requires approval — pass displayName before connecting. | não |
event_not_allowed | infra | The reserved protocol event was rejected by the server's deploy whitelist (ALLOWED_EVENTS) — a deploy configuration problem, not a code bug in the calling app. | não |
event_not_in_contract | usage | This event name is not declared in the local contract — add it to defineContract, or fix the typo. | não |
event_out_of_contract | infra | Received an event the local contract does not declare, or whose payload does not match the declared shape — not delivered to any handler. | não |
event_payload_invalid | usage | This payload does not match the shape declared for this event in the local contract. | não |
event_unknown_to_peer | usage | The peer's exchanged contract fingerprint does not declare this event name. The peer is running an outdated or divergent contract — update the peer, not this side. | não |
guest_url_reserved_param | usage | A reserved query param already exists on the guest URL — pass a URL without it, this library will not silently overwrite it. | não |
host_closed | usage | This host has already been closed (host.close()) — create a new one with createHost. | não |
idle_timeout | infra | The connection was idle without being associated to a room and the server closed it. Reconnect (a fresh call) to try again. | não |
invalid_access_mode | usage | accessMode was not one of the server's known access modes — this library validates accessMode client-side and should never let an invalid one through. | não |
invalid_creator_token | infra | The creator token was not recognized — another connection now controls this room. | não |
invalid_event | usage | The wire event name was invalid or reserved — this library controls the one reserved protocol event name and should never send a bad one. | não |
invalid_guest_url | usage | The guest URL could not be parsed. | não |
invalid_join_code | infra | The join code was wrong. Non-terminal for this connection — ask the user to re-enter it. | não |
invalid_max_guests | usage | maxGuests must be a positive integer — this library should validate it client-side before sending createHost/startRoom. | não |
invalid_room_id | usage | roomId does not match the server's expected shape — this library should have generated/validated a conforming id before sending. | não |
join_already_pending | usage | A join request is already pending on this connection — this library should never send a second join before the first resolves. | não |
join_code_required | usage | This accessMode requires a joinCode and none was provided. | não |
join_rejected | flow | The host rejected this join request. This attempt is over — reconnecting is a new admission, subject to a new approval. | não |
malformed_join_target | usage | target is malformed — expected {roomId, accessMode, joinCode?}. | não |
not_joined | usage | An event was sent before joining a room — this library should not allow sendEvent before a room association exists. | não |
occupancy_limit_not_honored | infra | The requested maxGuests was not honored by the server — the effective limit is reported alongside room creation. | não |
payload_too_large | infra | The server rejected an event payload as too large for its configured limit. | não |
payload_too_large_client | usage | The serialized event payload exceeds the usable budget for this event name. This library does not slice payloads — shrink it yourself before sending. | não |
protocol_version_mismatch | ended | Peer protocolVersion does not match this side's — there is no dual-stack support. Retrying will not help; update whichever side is running the older/newer build. | não |
qr_url_required | usage | generateQrImageDataUrl requires a non-empty url — pass the output of buildJoinUrl. | não |
request_id_required | usage | A join-decision requestId was missing — this library should always supply the id it was handed via onJoinRequest. | não |
request_not_found | usage | The join request no longer exists (already decided or expired) — this library should track pending requests and not decide on a stale one. | não |
role_required | usage | joinRoom requires role — it is never inferred from target, and the QR never carries it. | não |
room_already_exists | flow | roomId collided with an existing room. A caller-supplied roomId is not retried; a generated one is retried automatically by this library. | sim |
room_full | flow | The room already has effectiveMaxGuests guests. This attempt is over — the caller decides whether to retry, wait, or surface this to the user; the library never retries automatically. | não |
room_id_collision | usage | The caller-supplied roomId is already in use. This library never retries a caller-supplied id — pass a different one or omit roomId to let this library generate one. | não |
room_id_generation_exhausted | usage | Could not generate a free roomId after several attempts — extremely unlikely; check the server's room registry health. | não |
room_not_found | infra | The room no longer exists — it may have expired or been closed between the QR scan/typed code and this attempt. | não |
room_rate_limited | infra | Too many joinCode attempts against this room in a short window — the server is rate-limiting. Wait before trying again. | sim |
room_still_open | usage | startRoom() was called while the current session is still live — call room.close() before restarting. | não |
service_unavailable | infra | The server reported itself temporarily unavailable. | sim |
too_many_code_attempts | flow | Too many wrong joinCode attempts — the server closed this attempt. Ask the user to re-scan/re-enter and try again; this library never retries a code guess automatically. | não |
unknown_role | usage | role is not one of the known guest roles. The server accepts any string, but this library validates it at runtime so a bad value never reaches the wire unnoticed. | não |
unknown_type | infra | The server did not recognize a wire message's type. | não |
unsupported_guest_url_scheme | usage | The guest URL scheme is on the fixed refusal list and cannot be used. | não |
unsupported_qr_runtime | usage | event-room/qr only supports the "browser" runtime (it needs document) — generate the join URL with buildJoinUrl and render the QR another way outside a browser. | não |
Limite: o que usage garante sobre detectabilidade sem rede
A maioria dos códigos usage lança antes de qualquer I/O — são erros de programação puros (credencial ausente, role desconhecido, payload grande demais). Um deles não é assim: event_unknown_to_peer só existe depois do handshake de prontidão (a fingerprint do peer precisa ter chegado para saber se ele conhece o evento) — é usage, lança síncrono no ponto de chamada de sendEvent, mas depende de uma rodada de rede já ter acontecido antes. usage não é sinônimo de "detectável sem nunca ter tocado a rede"; é sinônimo de "erro de chamada, não de servidor".
Last updated on