---
title: "parseError"
description: "Hydrate unknown payloads or failed Response objects into BlypError instances on the server or in the browser."
canonical_url: "https://www.blyp.dev/docs/errors/parse-error"
markdown_url: "https://www.blyp.dev/docs/errors/parse-error.md"
last_updated: "2018-10-20"
x_farming_labs_generated_preamble: true
---

# parseError
URL: /docs/errors/parse-error
LLM index: /llms.txt
Description: Hydrate unknown payloads or failed Response objects into BlypError instances on the server or in the browser.

# `parseError()`

Use `parseError()` when the error source is not already a `BlypError`.

That usually means:

- a failed `fetch()` call returned a `Response`
- an API returned an unknown JSON payload
- you received a nested `{ error: ... }` shape from another service
- you want a consistent `BlypError` before rethrowing or logging

## Parse a raw payload

The root `parseError()` accepts payload-like objects and normalizes them into a `BlypError`.

```ts
import { parseError } from "@blyp/core";

const error = parseError({
  error: {
    status: 404,
    message: "User not found",
    fix: "Check the user id",
  },
});

throw error;
```

**Result shape:**

```json
{
  "status": 404,
  "message": "User not found",
  "fix": "Check the user id",
  "type": "BlypError"
}
```

## Parse a failed `Response`

```ts
import { parseError } from "@blyp/core";

const response = await fetch("https://api.example.com/payments");

if (!response.ok) {
  const error = await parseError(response);
  throw error;
}
```

**Result shape after parsing the failed response:**

```json
{
  "status": 502,
  "message": "Payment provider request failed",
  "type": "BlypError"
}
```

## Response parsing rules

- JSON bodies are preferred when the response is JSON
- nested `error` payloads are unwrapped
- text bodies become the message when JSON parsing fails
- `response.status` is authoritative even if the body contains a different status
- empty bodies fall back to `statusText`, then to the HTTP reason phrase

## Browser usage

Use the browser-safe client entry in frontend code:

```ts
import { parseError } from "@blyp/core/client";

const response = await fetch("/api/users/does-not-exist");

if (!response.ok) {
  throw await parseError(response);
}
```

## Common use cases

### Re-throwing upstream API failures

```ts
const response = await fetch("https://api.example.com/orders/ord_123");

if (!response.ok) {
  throw await parseError(response);
}
```

### Normalizing a third-party error payload

```ts
const payload = await queueClient.publish(job);

if ("error" in payload) {
  throw parseError(payload);
}
```

### Logging once while parsing

`parseError()` does not log by default, but it can emit exactly once when you pass a logger.

```ts
const error = await parseError(response, {
  logger,
  logLevel: "warning",
});
```

This is useful when a boundary layer should normalize and log an error before handing it to the rest of the system.

## When not to use it

If you are creating the error yourself, prefer [createError](/docs/errors/create-error). `parseError()` is for hydration and normalization, not primary error construction.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).