---
title: "Error handling"
source: https://dev.pageseeder.com/api/usage/error_codes.html
description: "This document describes error codes and responses returned by PageSeeder services. It covers core error codes (0x01xx through 0x08xx) with their HTTP status codes, XML/JSON response formats, and explanations for scenarios like permission failures, missing parameters, and generator errors."
last_updated: 2026-08-11T14:53:29+10:00
tokens: ~1330
---

# Error codes

## Services

Whenever a fatal error occurs during the execution of a service, the following XML is returned:

```xml
<error id="[Error ID]">
  <request>[Service URL]</request>
  <message>[Error message]</message>
</error>
```

If the request was a JSON request, the error response looks like:

```json
{
  "id": "[Error ID]",
  "request": "[Service URL]",
  "message": "[Error message]",
}
```

The HTTP status code is also set accordingly depending on whether it is a client error. For example, 400 for missing parameters, 500 for server errors.

Most errors occurring while a service is invoked have a specific identifier and are returned by the underlying generator. These are described in the documentation of each generator.

However, some errors are caught by the service framework.

## Core error codes

### `0x0101` – Failed permission check

When the user invoking the service does not have the required permission.

#### If the user is already logged in

```xml

<error id="0101">
  <request>[Service URL]</request>
  <message>Access forbidden</message>
</error>
```

 HTTP status: `403`

#### If the user is not logged in

```xml

<error id="0101">
  <request>[Service URL]</request>
  <message>Unauthorized access</message>
</error>
```

### `0x0102` – Service Not Found

When there is no service corresponding to the specified URL

```xml

<error id="0102">
  <request>[Service URL]</request>
  <message>Unable to find requested service</message>
</error>
```

HTTP status: `404`

### `0x0103` – Bad tunnel

When a service was invoked with the wrong HTTP method.

```xml

<error id="0103">
  <request>[Service URL]</request>
  <message>Unable to tunnel request through specified HTTP method</message>
</error>
```

HTTP status: `400`

### `0x0104` – Bad content type

When the content type requested cannot be provided with this service.

```xml

<error id="0104">
  <request>[Service URL]</request>
  <message>Unable to provide acceptable content type</message>
</error>
```

HTTP status: `406`

### `0x0201` – Missing parameter

When a required parameter was not specified in the URL. The error message returns the list of missing required parameters if possible.

```xml

<error id="0201">
  <request>[Service URL]</request>
  <message>Failed @Requires check: missing parameter '[name]'</message>
</error>
```

HTTP status: `400`

### `0x0202` – Group not found

When the `{group}` URL variable does not resolve to an existing group.

```xml

<error id="0202">
  <request>[Service URL]</request>
  <message>Failed @Requires check: missing Group instance</message>
</error>
```

HTTP status: `400`

### `0x0204` – Member not found

When the `{member}` URL variable does not resolve to an existing member.

```xml
<error id="0204">
  <request>[Service URL]</request>
  <message>Failed @Requires check: missing Member instance</message>
</error>
```

### `0x0208` – URI not found

When the `{uri}` URL variable does not resolve to an existing URI.

```xml
<error id="0208">
  <request>[Service URL]</request>
  <message>Failed @Requires check: missing URI instance</message>
</error>
```

HTTP status: `400`

### `0x02xx` – Other failed requirement

When multiple requirements failed, the error code is a combination of the missing elements. For example, if a service was invoked on a non-existent member (0x0204) and with a missing parameter (0x0201), the combined code is **0x0205**.

```xml
<error id="02xx">
  <request>[Service URL]</request>
  <message>Failed @Requires check: [...]</message>
</error>
```

HTTP status: `400`

### `0x0600` – Generator not found

When the generator bound to the service could not be found in the classpath. This generally indicates a configuration or deployment error: the PageSeeder services configuration references a generator which cannot be found.

```xml

<error id="0600">
  <request>[Service URL]</request>
  <message>Unable to find generator class</message>
</error>
```

HTTP status: `503`

### `0x0601` – Generator instantiation error

When the underlying generator could not be instantiated because an error occurred.

```xml

<error id="0601">
  <request>[Service URL]</request>
  <message>Unable to instantiate the generator</message>
</error>
```

HTTP status: `503`

### `0x0602` – Generator initialization error

When the underlying generator could not be initialized because an error occurred while invoking the `init()` method.

```xml

<error id="0602">
  <request>[Service URL]</request>
  <message>Unable to initialize the generator, init() method failed</message>
</error>
```

HTTP status: `503`

### `0x0800` – Exception caught

When the underlying generator threw an exception.

```xml

<error id="0800">
  <request>[Service URL]</request>
  <message>Runtime exception thrown by generator</message>
</error>
```

HTTP status: `500`

### `0x0801` – Generator Exception

When the underlying generator threw a specific exception.

```xml

<error id="0801">
  <request>[Service URL]</request>
  <message>Exception thrown by generator on purpose</message>
</error>
```

HTTP status: `500`

### `0x0802` – Database error

When the underlying generator threw a database error.

```xml

<error id="0802">
  <request>[Service URL]</request>
  <message>Database exception thrown by generator</message>
</error>
```

HTTP status: `502`