> ## Documentation Index
> Fetch the complete documentation index at: https://docs.primevault.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Status Codes

> HTTP status codes returned by the PrimeVault API, the matching JavaScript SDK error classes, and retry guidance for each failure type.

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. |

<Note>
  For transactions and approval-backed resources, inspect the returned `status` field after a `200` or `201` response.
</Note>

## 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

```typescript theme={null}
class BaseAPIException extends Error {
  message: string;
  errorCode?: string;
  status?: number;
  responseText?: unknown;
}
```

```typescript theme={null}
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. |

<Warning>
  Do not blindly retry transaction or resource creation. Use a stable `externalId` where supported and retrieve the resulting resource before deciding whether to resubmit.
</Warning>

## 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](/api-basics/custom-error-codes).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.