어떤 오류를 재시도해야 하나요?

429는 백오프를 두고, 502는 즉시 한 번 재시도하세요. 403은 재시도하지 마세요. 어느 변형도 두 번째 시도에서 성공하지 않습니다. 트랜잭션 순회에서 나온 -400도 재시도하지 마세요. 그것은 경계이지 일시적 장애가 아닙니다. 651은 노드가 뒤처졌거나 블록이 저장소 밖에 있다는 뜻입니다. 최신 블록이면 기다렸다가 재시도하고, 오래된 블록이면 아카이브를 사용하세요.

왜 getTransactions에서는 403이 나오고 getAccountState에서는 안 나오나요?

getAccountState는 라이트 노드가 항상 가지고 있는 현재 상태를 읽습니다. 트랜잭션 순회는 시간을 거슬러 올라가며, 라이트 노드의 약 이틀치 창을 넘어서면 게이트웨이가 아카이브 노드로 라우팅하는데, 아카이브가 없는 플랜은 이를 사용할 수 없습니다. 403의 텍스트가 이유를 말해 줍니다: archive history is not included in this plan.

651과 -503의 차이는 무엇인가요?

651은 노드 소프트웨어의 ErrorCode::notready입니다. 데이터는 원칙적으로 존재하지만 이 노드에 준비되어 있지 않은 경우입니다. 아직 적용되지 않은 블록이거나, 데이터베이스 밖의 lt입니다. -503 timeout은 노드 자체의 쿼리별 기한입니다. 데이터는 있었지만 제때 응답을 구성하지 못한 것입니다.

무료 도구

TON liteserver 오류 코드

TONNode 게이트웨이나 TON 노드가 반환할 수 있는 모든 liteServer.error를 무슨 일이 일어났는지와 어떻게 해야 하는지와 함께 정리했습니다. 게이트웨이 행은 LiteServers 문서에서 가져왔고, 노드와 클라이언트 행은 ton-blockchain/ton에서 해당 오류가 발생하는 위치로 연결됩니다.

검색

18개 중 18개 코드

코드	메시지	무슨 일이 일어났나	어떻게 할까
403	`archive history is not included in this plan` TONNode 게이트웨이	쿼리가 라이트 노드가 더 이상 보관하지 않는 블록을 필요로 했고, 플랜에 아카이브 범위가 없습니다. 라이트 노드는 현재 블록 생성 속도 기준으로 약 이틀치 기록을 보관하며, 그보다 오래된 요청은 게이트웨이가 아카이브 노드로 라우팅하고 플랜에 아카이브가 없으면 거부합니다.	플랜에 아카이브를 추가하거나 더 최근 블록을 조회하세요. 재시도해도 소용없습니다. 같은 쿼리는 다시 거부됩니다. 출처: LiteServers docs, Chapter 4
403	`method not supported` TONNode 게이트웨이	요청 타입이 게이트웨이의 메서드 테이블에 없거나, waitMasterchainSeqno 접두사 하나에 쿼리 하나보다 긴 배치를 보냈습니다.	문서화된 메서드를 접두사 없이, 또는 단일 접두사와 함께 사용하세요. 플랜에 아카이브를 추가해도 달라지지 않습니다. 출처: LiteServers docs, Chapter 5
429	`too many requests` TONNode 게이트웨이	플랜의 속도 제한입니다. API 키별 leaky bucket이 비용 단위로 계산됩니다: 일반 읽기 5, getTransactions 한 페이지 최대 16, 블록 전체 50.	잠시 물러났다가 재시도하세요. 지속된다면 플랜의 충전 속도에 맞춰 클라이언트 속도를 조절하거나 플랜을 올리세요. 출처: LiteServers docs, Chapter 7
429	`too many concurrent requests for this key` TONNode 게이트웨이	이 키에서 동시에 열린 쿼리가 플랜 허용치보다 많았습니다: 플랜 RPS의 절반, 최소 8, 최대 128. 속도가 아니라 진행 중 작업 수에 대한 상한입니다.	팬아웃을 제한하세요. 제한 없는 Promise.all이나 고루틴 팬아웃은 속도 제한보다 훨씬 먼저 이 상한에 부딪힙니다. 출처: LiteServers docs, Chapter 7
429	`gateway is saturated, retry shortly` TONNode 게이트웨이	모든 고객을 통틀어 진행 중 쿼리 256개라는 전역 상한에 도달했습니다. 플랜이 아니라 백엔드가 힘든 상태입니다.	백오프를 두고 재시도하세요. 출처: LiteServers docs, Chapter 7
502	`backend node timeout` TONNode 게이트웨이	노드가 게이트웨이의 시간 창 안에 응답하지 않았습니다: 라이트 노드 7초, 아카이브 20초.	즉시 한 번 재시도하세요. 클라이언트 타임아웃을 이 값보다 높게 설정하세요. 그렇지 않으면 실제 오류가 로컬 타임아웃으로 바뀌어 진단 정보를 잃게 됩니다. 출처: LiteServers docs, Chapter 5
400	`canceled` TONNode 게이트웨이	쿼리 도중에 컨텍스트나 연결이 사라졌습니다. 보통 자신의 타임아웃이 먼저 발동한 경우입니다.	클라이언트 측 문제입니다. 클라이언트 타임아웃을 게이트웨이의 7초 / 20초 창보다 높이세요. 출처: LiteServers docs, Chapter 5
400	`non zero mode is not supported` TONNode 게이트웨이	getMasterchainInfoExt를 0이 아닌 mode로 호출했습니다.	mode: 0을 보내세요. 출처: LiteServers docs, Chapter 5
-400	`unknown request type` TONNode 게이트웨이	메서드가 플랜 검사는 통과하지만 게이트웨이의 요청 핸들러가 구현하지 않았습니다.	재시도할 것이 없습니다. 메서드 참조에서 지원됨으로 표시된 메서드를 사용하세요. 출처: LiteServers docs, Chapter 5
500	`failed to …` TONNode 게이트웨이	게이트웨이가 응답을 구성하지 못했습니다.	재시도하세요. 계속되면 저희 쪽 문제입니다. 키 id와 시각을 적어 지원팀에 알려 주세요. 출처: LiteServers docs, Chapter 5
-400	`cannot locate transaction in block with specified logical time` TON 노드	getTransactions 순회가 노드가 예상한 블록에서 찾지 못하는 트랜잭션에 도달했습니다. 대개 순회가 라이트 노드의 저장 창을 넘어선 경우입니다.	아카이브 플랜에서는 게이트웨이가 자동으로 아카이브에 재시도합니다. 아카이브가 없다면 이것이 기록의 경계입니다. 일시적 장애가 아니니 재시도하지 마세요. 출처: validator/impl/liteserver.cpp, LiteQuery::continue_getTransactions
-400	`… (other node text)` TON 노드	노드 자체가 쿼리에 실패하고 자신의 텍스트를 보고했습니다. -400은 노드 소프트웨어에서 LiteQuery 실패의 기본 코드입니다. 흔한 텍스트: invalid block id requested, shard not found, cannot unpack block header.	텍스트를 읽으세요. 잘못된 블록 id나 샤드는 요청의 버그이고, 저장소 관련 텍스트는 블록이 이 노드가 보관하는 범위 밖에 있다는 뜻입니다. 출처: validator/impl/liteserver.hpp, LiteQuery::fatal_error default code
-503	`timeout` TON 노드	노드가 응답을 구성하는 동안 노드 자체의 쿼리별 기한이 지났습니다. 무거운 증명, 느린 디스크, 또는 콜드 스토리지에서 가져와야 하는 블록 때문입니다.	한 번 재시도하세요. 특정 쿼리가 항상 타임아웃된다면 범위를 줄이세요. 페이지당 트랜잭션 수를 줄이거나 더 가벼운 메서드를 쓰세요. 출처: validator/impl/liteserver.cpp, LiteQuery::alarm
651	`block … is not applied` TON 노드	노드에 블록은 있지만 아직 적용하지 않았습니다. 노드가 아직 따라잡는 중이거나, 요청한 seqno가 노드의 상태보다 앞서 있습니다. seqno가 노드보다 앞설 때 텍스트는 "(last known masterchain block: N)"으로 끝납니다.	노드가 따라잡을 때까지 기다렸다가 재시도하세요. seqno를 직접 계산한다면 getMasterchainInfo가 보고하는 것보다 새로운 블록을 요청하지 마세요. 출처: validator/manager.cpp, process_block_handle_for_litequery_error
651	`block … is not in db` TON 노드	노드가 그 블록을 받은 적이 없습니다. 노드가 가진 것보다 새롭거나, 보관하는 것보다 오래된 블록입니다.	현재 마스터체인 정보와 함께 lookupBlock을 사용해 존재하는 블록을 찾으세요. 오래된 블록에는 아카이브 범위가 필요합니다. 출처: validator/manager.cpp, process_block_handle_for_litequery_error
651	`lt not in db` TON 노드	논리 시간으로 lookupBlock을 호출했는데 이 노드의 어떤 블록 인덱스도 그 lt를 포함하지 않습니다. 노드의 저장소보다 오래되었거나, 그 lt를 가진 블록이 존재하지 않습니다.	가능하면 seqno나 utime으로 조회하세요. 과거의 lt에는 아카이브 플랜을 사용하세요. 출처: validator/db/archive-manager.cpp, ArchiveManager::get_block_by_lt
652	`timeout for adnl query …` C++ 클라이언트	C++ 클라이언트(lite-client, tonlib)의 ADNL 쿼리 계층이 응답 대기를 포기했습니다. Python, JavaScript, Go 라이브러리는 이 코드 대신 자체 타임아웃 오류를 발생시킵니다.	클라이언트 타임아웃을 게이트웨이의 7초 / 20초 창보다 높이고 네트워크 경로를 확인하세요. 게이트웨이가 502로 응답했다면 그것이 진짜 원인입니다. 출처: adnl/adnl-query.cpp, AdnlQuery::alarm
651	`not ready / conn not ready` C++ 클라이언트	C++ 클라이언트가 liteserver와의 핸드셰이크가 끝나기 전에, 또는 연결이 끊어진 뒤에 쿼리를 보냈습니다.	연결이 준비될 때까지 기다리고(라이브러리가 대신 처리합니다), 유휴 연결이 닫히면 다시 연결하세요. 정상적인 동작입니다. 출처: adnl/adnl-ext-client.cpp, AdnlExtClientImpl::send_query

651 = ErrorCode::notready, 652 = ErrorCode::timeout — common/errorcode.h

브라우저에서 실행됩니다. 붙여 넣은 내용은 이 페이지를 벗어나지 않습니다.

liteserver 오류 읽는 법

liteserver는 모든 쿼리에 대해 요청된 객체 또는 정수 code와 message를 담은 liteServer.error로 응답합니다. TONNode 게이트웨이도 자신의 거부에 같은 봉투를 사용하므로, 라이브러리는 이를 다른 노드 오류와 똑같이 보여줍니다. tonutils-go는 코드를 ton.LSError에 보관하고, pytoniq는 .code와 .message를 가진 LiteServerError를 발생시키며, ton-lite-client는 메시지가 텍스트뿐인 Error를 던집니다.

코드는 두 곳에서 오며, 표는 어느 쪽인지 표시합니다.

게이트웨이 코드 — 400, 403, 429, 500, 502 — 는 ADNL 연결과 노드 사이에 있는 TONNode 게이트웨이가 생성합니다. 게이트웨이는 메서드를 플랜과 대조하고, 속도 제한과 동시성 상한을 적용하며, 쿼리를 라이트 노드나 아카이브 노드로 라우팅합니다. 이 행들은 LiteServers 문서 5장을 다시 정리한 것입니다.
노드 코드는 ton-blockchain/ton의 노드 소프트웨어에서 옵니다. -400은 LiteQuery 실패 텍스트가 전송될 때의 기본 코드이고, -503 timeout은 노드 자체의 쿼리별 기한이며, 651과 652는 common/errorcode.h의 ErrorCode::notready와 ErrorCode::timeout입니다. 두 행은 서버가 아니라 C++ 클라이언트(lite-client, tonlib) 자체가 발생시키는 것이며, 다른 언어는 그런 상황에서 자체 예외를 발생시킵니다.

가장 중요한 것들

403 archive history is not included in this plan. 기록을 순회할 때 중요한 유일한 신호입니다. 쿼리가 라이트 노드가 더 이상 보관하지 않는 블록을 필요로 했고(라이트 노드는 현재 블록 생성 속도 기준으로 약 이틀치 기록을 보관하는데, 이는 약속이 아니라 대략의 규모입니다) 플랜에 아카이브 범위가 없는 경우입니다. 재시도할 수 없습니다. 플랜에 아카이브를 추가하거나 더 최근 블록을 요청하세요. 4장은 경계가 어디인지 설명하고, 키에 대해 경계를 측정하는 프로브를 포함합니다.

429, 세 가지 다른 제한. too many requests는 키별 속도 제한으로, 비용 단위로 계산되는 leaky bucket입니다. 일반 읽기는 5, getTransactions 한 페이지는 최대 16, 블록 전체는 50입니다. too many concurrent requests for this key는 진행 중 상한으로, 플랜 RPS의 절반이며 최소 8, 최대 128입니다. gateway is saturated는 모든 고객을 통틀어 진행 중 쿼리 256개라는 전역 상한입니다. 앞의 둘은 클라이언트가 속도를 조절해야 한다는 뜻이고, 마지막은 백엔드가 힘들다는 뜻이며 올바른 대응은 백오프입니다. 7장에 비용 표와 속도를 조절하는 클라이언트 코드 조각이 있습니다.

502 backend node timeout. 노드가 게이트웨이의 시간 창 안에 응답하지 않았습니다. 라이트 노드 7초, 아카이브 20초입니다. 클라이언트 타임아웃을 이 값보다 높게 설정하세요. 더 짧은 타임아웃은 실제 502를 로컬 타임아웃으로 바꾸고 진단 정보를 잃게 합니다.

651과 "not in db" 계열. block … is not applied, block … is not in db, lt not in db는 모두 ErrorCode::notready를 가집니다. 이 노드에 요청한 것이 준비되어 있지 않다는 뜻입니다. 아직 따라잡는 중이거나, 블록이 노드의 상태보다 앞서 있거나, 블록이나 논리 시간이 저장소보다 오래된 경우입니다. 새 블록은 저절로 나타나고, 오래된 블록에는 아카이브가 필요합니다.

무엇을 재시도할까

429는 백오프를 두고, 502는 즉시 한 번 재시도하세요. 403은 재시도하지 마세요. 어느 변형도 두 번째 시도에서 성공하지 않습니다. 트랜잭션 순회에서 나온 -400도 재시도하지 마세요. 경계이지 일시적 장애가 아닙니다. 651의 경우 노드 상태보다 새로운 블록은 잠시 후 재시도하고, 저장소보다 오래된 블록은 재시도를 멈추세요.

멤풀 스트림 오류

멤풀 스트림은 자체 오류 목록을 가진 별개의 프로토콜입니다. JSON error 메시지와 4401, 4429 같은 WebSocket 종료 코드가 있으며, 이 표에서는 다루지 않습니다.

자주 묻는 질문

어떤 오류를 재시도해야 하나요?: 429는 백오프를 두고, 502는 즉시 한 번 재시도하세요. 403은 재시도하지 마세요. 어느 변형도 두 번째 시도에서 성공하지 않습니다. 트랜잭션 순회에서 나온 -400도 재시도하지 마세요. 그것은 경계이지 일시적 장애가 아닙니다. 651은 노드가 뒤처졌거나 블록이 저장소 밖에 있다는 뜻입니다. 최신 블록이면 기다렸다가 재시도하고, 오래된 블록이면 아카이브를 사용하세요.
왜 getTransactions에서는 403이 나오고 getAccountState에서는 안 나오나요?: getAccountState는 라이트 노드가 항상 가지고 있는 현재 상태를 읽습니다. 트랜잭션 순회는 시간을 거슬러 올라가며, 라이트 노드의 약 이틀치 창을 넘어서면 게이트웨이가 아카이브 노드로 라우팅하는데, 아카이브가 없는 플랜은 이를 사용할 수 없습니다. 403의 텍스트가 이유를 말해 줍니다: archive history is not included in this plan.
651과 -503의 차이는 무엇인가요?: 651은 노드 소프트웨어의 ErrorCode::notready입니다. 데이터는 원칙적으로 존재하지만 이 노드에 준비되어 있지 않은 경우입니다. 아직 적용되지 않은 블록이거나, 데이터베이스 밖의 lt입니다. -503 timeout은 노드 자체의 쿼리별 기한입니다. 데이터는 있었지만 제때 응답을 구성하지 못한 것입니다.
왜 제 라이브러리는 이 표와 다른 오류를 보여주나요?: 라이브러리마다 liteServer.error를 다르게 감쌉니다. tonutils-go는 코드를 ton.LSError에 보관하고, pytoniq는 code와 message를 가진 LiteServerError를 발생시키며, ton-lite-client는 텍스트만 담은 Error를 던집니다. 코드를 얻을 수 없을 때는 텍스트로 대조하세요.

프라이빗 liteserver 액세스Litenode 및 Archive 플랜: 자신의 키로 체인을 직접 조회하세요.LiteServers 문서모든 메서드, 속도 제한, 아카이브 라우팅, 그리고 전체 오류 장.

다른 도구

TON 주소 변환기 및 검증기Raw ↔ EQ ↔ UQ, 메인넷과 테스트넷, 체크섬 검사, 일괄 모드.nanoton ↔ GRAM (TON) 및 jetton 단위 변환기소수 9자리 GRAM ↔ nanoton, 그리고 임의 decimals의 jetton 수량 ↔ raw 단위.BoC에서 TON 메시지 해시 계산모든 메시지 BoC의 cell_hash, TEP-467 norm_hash, sha256. hex와 base64.