Custom Error Codes

primevault error responses combine an http status with a human readable message and, for known failures, a machine readable custom code the http status remains authoritative for the broad failure class; the custom code enables precise handling inside that class error response format { "message" "vault has insufficient balance to complete the transaction", "code" "4003" } field required description message yes human readable diagnostic text suitable for logs and operator facing messages after sensitive values are removed code no stable machine readable primevault error code for a known failure generic validation failures can use "400" , and a few low level failures may omit it branch program logic on code when a documented code exists use message as diagnostic context, not as a stable identifier handling order inspect the http status and typed sdk error class read the custom errorcode when present apply handling for that documented code fall back to the http status and message when no custom code is available preserve the original status and code in structured logs, without logging credentials or sensitive request data typescript / javascript the sdk error carries message , errorcode , status , and responsetext import { badrequesterror, toomanyrequestserror, } from "@primevault/js api sdk"; try { await apiclient createtransfertransaction({ source, destination, amount, asset, chain, }); } catch (error) { if (error instanceof badrequesterror) { switch (error errorcode) { case "4003" // insufficient balance break; case "4011" // compliance or ofac restriction break; case "4013" // invalid transaction parameters break; default console error(error status, error message); } } else if (error instanceof toomanyrequestserror) { // retry with bounded exponential backoff and jitter } } python the python sdk error exposes response text and code from primevault python sdk base api client import badrequesterror try api client create transfer transaction(request) except badrequesterror as error if error code == "4003" \# insufficient balance else \# fall back to the http class and diagnostic message print(error response text) retry safety do not retry a known validation, permission, compliance, or insufficient balance error unchanged retry 429 and transient 5xx responses only with bounded backoff code reference use the child pages in this section for endpoint specific custom codes transaction contains the transaction error code table and handling meanings