Skip to main content
All SDK exceptions inherit from ToncenterError. Catch it to handle any error from the library. 
from toncenter.exceptions import ToncenterError

​
Client Errors

CodeExceptionDescription
400ToncenterBadRequestErrorCheck query parameters, request body, and path arguments.
401ToncenterUnauthorizedErrorInvalid API key. Obtain one via @toncenter bot.
403ToncenterForbiddenErrorAPI key was issued for a different network.
404ToncenterNotFoundErrorResource does not exist.
405ToncenterMethodNotAllowedErrorUse GET or POST.
409ToncenterConflictErrorResource does not match the expected type.
422ToncenterUnprocessableErrorParameters failed validation.
429ToncenterTooManyRequestsErrorRate limit exceeded. Back off and retry.

​
Server Errors

CodeExceptionDescription
500ToncenterInternalServerErrorInternal server error.
504ToncenterGatewayTimeoutErrorLiteserver timeout. Retry the request.
542ToncenterLiteServerErrorLiteserver error or unsupported TVM stack type.
V2 API may return all listed codes. V3 API typically returns 401, 404, 409, 422, and 500.

​
Other Exceptions

ExceptionWhen
ToncenterConnectionErrorDNS failure, TCP timeout, or refused connection — before any HTTP response.
ToncenterValidationErrorResponse body did not match the expected Pydantic model.
ToncenterSessionErrorRequest made before client session was initialized.
ToncenterConnectionLimitErrorStreaming connection limit reached. Auto-rotates with multiple keys; fatal with single key.
ToncenterStreamingErrorTransport-level error during streaming.
ToncenterConnectionLostErrorReconnect limit exhausted during streaming.
ToncenterRetryErrorAll retry attempts exhausted.