Status Codes - Mintlify Starter Kit

The PrimeVault API uses standard HTTP status codes to describe the transport-level outcome of each 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`

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.

⌘I