API error handling
This page describes the most common types of errors (exceptions) that may occur when issuing API requests.
REST
A server may respond to a REST API request with an HTTP response message informing about the failure of the API call. For example, if you send a simple request such as:
https://demopublic.magnolia-cms.com/.rest/delivery/tours/v1/magnolia-travels/A-Taste-of-Asia
the sever responds with the following message in the body of the response:
{ "error": { "code": "pathNotFound", "message": "/magnolia-travels/A-Taste-of-Asia" } }
The message informs the receiver about an exception that occurred while processing the request: the requested resource path was not found on the server.
Exception types
The tables below describe several common types of exceptions, their HTTP
status codes and error codes. For exceptions not mentioned below, the
status code is 500 and the error code is unknown
.
JAX-RS exceptions
Exception | HTTP Status Code | Error code | Description |
---|---|---|---|
|
401 |
|
Unauthorized. |
|
400 |
|
Bad request. |
|
405 |
|
The request method is not supported. |
|
406 |
|
The requested media type is not supported. |
|
404 |
|
The resource was not found. |
|
400 |
|
A JAX-RS exception. |
|
500 |
|
A JAX-RS exception. |
Repository exceptions
Exception | HTTP Status Code | Error code | Description |
---|---|---|---|
|
403 |
|
Access is denied. |
|
500 |
|
The requested node type was not found. |
|
500 |
|
The requested workspace is not configured. |
|
400 |
|
The value format is invalid. |
|
400 |
|
The query is invalid. |
|
404 |
|
The requested resource path was not found. |
Exception response format
The format of an exception response to be returned is determined as follows:
-
The response is displayed in the media type requested (see IANA’s Media Types).
-
If the requested media type is not supported, JSON is returned as fallback.
-
If no resource method is matched, JSON is returned as fallback.