Status Codes

http status codes describe the transport level outcome of a request a successful write means the request was accepted or the resource was created; it does not mean an asynchronous vault or transaction lifecycle has completed success responses status meaning typical use 200 ok request completed successfully reads, updates, actions, quotes, and fee estimates 201 created resource was created vault, contact, bank account, and transaction creation for transactions and approval backed resources, inspect the returned status field after a 200 or 201 response client and authorization errors status meaning javascript sdk error 400 bad request invalid payload, unsupported state transition, or business rule failure badrequesterror 401 unauthorized missing, expired, or invalid request authentication unauthorizederror 403 forbidden authenticated api user lacks permission or resource scope forbiddenerror 404 not found resource does not exist in the request scope notfounderror 408 request timeout server timed out waiting for the request requesttimeouterror 409 conflict request conflicts with current resource state conflicterror 422 unprocessable entity structured validation failed validationerror 429 too many requests organization or endpoint rate limit exceeded toomanyrequestserror a 404 can intentionally hide a resource outside the api user's organization scope do not retry it with ids from another organization server and gateway errors status meaning javascript sdk error 500 internal server error unexpected server failure internalservererror 502 bad gateway upstream gateway returned an invalid response badgatewayerror 503 service unavailable service is temporarily unavailable serviceunavailableerror 504 gateway timeout upstream service timed out gatewaytimeouterror other unexpected status unmapped http response unknownerror a network failure without an http response is surfaced as networkerror typed sdk error shape class baseapiexception extends error { message string; errorcode? string; status? number; responsetext? unknown; } import { notfounderror } from "@primevault/js api sdk"; try { await apiclient getvaultbyid("vault 123"); } catch (error) { if (error instanceof notfounderror) { console error(error status, error errorcode, error message); } } retry guidance failure default behavior 400 , 401 , 403 , 404 , 409 , 422 fix the request, credentials, permissions, or resource state before retrying 408 or 429 retry with bounded exponential backoff and jitter respect retry after when present 500 , 502 , 503 , 504 retry safe reads with bounded backoff network failure confirm whether the server received the request before repeating a write do not blindly retry transaction or resource creation use a stable externalid where supported and retrieve the resulting resource before deciding whether to resubmit http status versus custom error code the http status tells you the broad failure class the json code identifies a specific primevault business or validation failure when one is available handle both; see custom error codes