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

# Errors

> Handle Swish API errors using the standard error envelope and HTTP status codes.

When a request fails, the Swish API returns a JSON error response with a consistent structure. The HTTP status code indicates the category of failure, and the response body provides details for debugging.

## Error format

All error responses use the same envelope:

```json theme={null}
{
  "error": {
    "message": "Item not found",
    "error": "Not Found",
    "statusCode": 404,
    "requestId": "123e4567-e89b-12d3-a456-426614174000"
  }
}
```

| Field | Type | Description |
| - | - | - |
| `message` | `string` | A human-readable description of what went wrong. |
| `error` | `string` | The HTTP error type (e.g., `"Not Found"`, `"Bad Request"`). |
| `statusCode` | `number` | The HTTP status code, matching the response status. |
| `requestId` | `string` | A unique identifier for the request. Include this when contacting support. |

## Status codes

| Code | Error | Description |
| - | - | - |
| `400` | Bad Request | The request body or query parameters are invalid or missing. |
| `401` | Unauthorized | The `Authorization` header is missing or the token is invalid. |
| `403` | Forbidden | The token is valid but does not have permission for this operation. |
| `404` | Not Found | The requested resource does not exist. |
| `429` | Too Many Requests | You have exceeded the [rate limit](https://swish.app/docs/references/api/rate-limits.md). |
| `500` | Internal Server Error | An unexpected error occurred on the server. Retry with backoff. |

## Handling errors

```typescript @swishapp/api-client theme={null}
import { createApiClient } from "@swishapp/api-client/2026-07";

const client = createApiClient({
  authToken: "your-api-token",
});

const result = await client.items.findById("nonexistent-id");

if ("error" in result) {
  console.error(`${result.error.statusCode}: ${result.error.message}`);
  console.error(`Request ID: ${result.error.requestId}`);
} else {
  console.log(result.data);
}
```

```typescript JavaScript theme={null}
const response = await fetch(
  "https://swish.app/api/2026-07/items/nonexistent-id",
  { headers: { Authorization: "Bearer your-api-token" } },
);

if (!response.ok) {
  const { error } = await response.json();
  console.error(`${error.statusCode}: ${error.message}`);
  console.error(`Request ID: ${error.requestId}`);
}
```

```bash cURL theme={null}
curl -i https://swish.app/api/2026-07/items/nonexistent-id \
  -H "Authorization: Bearer your-api-token"

# HTTP/1.1 404 Not Found
# {
#   "error": {
#     "message": "Item not found",
#     "error": "Not Found",
#     "statusCode": 404,
#     "requestId": "123e4567-e89b-12d3-a456-426614174000"
#   }
# }
```

> [!TIP]
>
> The `@swishapp/api-client` never throws on API errors. Instead, every response
> is a union: check for `"error" in result` to distinguish failures from
> successful responses.

## Request ID

Every response - successful or failed - includes a `requestId`. When reporting an issue to [Swish support](mailto:support@swish.app), include the request ID so the team can look up the exact request in the logs.


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