Error Handling

This page describes the error responses returned by the API, and which endpoints each error applies to.

All error responses use the same JSON structure, regardless of the endpoint that produced them.

Note: Successful responses differ between endpoints (a raw object, data with pagination, { "id": 1 }, or { "success": true }). Error responses are always uniform.

Error Response Format

{
    "success": false,
    "error": {
        "code": "VALIDATION_FAILED",
        "message": "One or more fields are invalid.",
        "details": [
            {
                "field": "price",
                "message": "Must be a number."
            }
        ]
    }
}

Error Response Fields

Field	Type	Description
`success`	boolean	Always `false` for an error response.
`error`	object	Describes the error that occurred.
`error.code`	string	A stable, machine-readable error code. Use this value in client code to handle specific errors.
`error.message`	string	A human-readable description of the error. This text may change and should not be used for logic.
`error.details`	array	Optional. A list of field-level problems, mainly returned with `400` and `422` responses.
`error.details[].field`	string	The name of the field or parameter that caused the problem.
`error.details[].message`	string	A description of the problem with that field.

Endpoint Reference

The following abbreviations are used throughout this page.

Abbreviation	Endpoint	Method and Route
View	View	`GET /{contentType}/{id}` and `GET /{contentType}/{id}/layout/{layoutId}`
List	List	`POST /{contentType}`
Store	Store	`POST /{contentType}/store`
Update	Update	`POST /{contentType}/{id}`
Restore	Restore	`POST /{contentType}/{id}/restore`
Delete	Delete	`DELETE /{contentType}/{id}`

Error Codes

400 Bad Request

The request could not be understood or contains invalid parameters.

Error Code	Triggered When	Applies To
`MALFORMED_REQUEST`	The request body is not valid JSON, or `page`, `pageSize` or `layout` are not integers.	List, Store, Update
`INVALID_PARAMETER`	`id` or `layoutId` in the path is not an integer.	View, Update, Restore, Delete
`MISSING_REQUIRED_PARAMETER`	`page` or `pageSize` is missing (List), or `layout` or `item` is missing (Store, Update).	List, Store, Update
`INVALID_PAGINATION`	`page` is less than `1`, `pageSize` is less than `1`, or `pageSize` exceeds the maximum allowed.	List
`INVALID_FILTER`	A filter uses an unknown operator, refers to an unknown `field`, or has a `value` that does not suit the operator. For example, `BETWEEN` without two values, `IN` without an array, or a date operator on a non-date field.	List
`INVALID_ORDERING`	`ordering.field` does not exist, or `ordering.order` is not `asc` or `desc`.	List

401 Unauthorized

Error Code	Triggered When	Applies To
`UNAUTHENTICATED`	The bearer token is missing, malformed, invalid or expired.	All endpoints

403 Forbidden

Error Code	Triggered When	Applies To
`FORBIDDEN`	The token is valid, but the user does not have permission for this content type, for this action, or for the object's `group_id`.	All endpoints

404 Not Found

Error Code	Triggered When	Applies To
`CONTENT_TYPE_NOT_FOUND`	The `{contentType}` route is not configured in the API.	All endpoints
`OBJECT_NOT_FOUND`	No object with the given `id` exists for the content type.	View, Update, Restore, Delete
`LAYOUT_NOT_FOUND`	The layout does not exist, or does not belong to the content type.	View (with `layoutId`), List, Store, Update

405 Method Not Allowed

Error Code	Triggered When	Applies To
`METHOD_NOT_ALLOWED`	The wrong HTTP method is used for the route. For example, `GET` on the List route, or `POST` on the View route.	All endpoints

409 Conflict

The request is valid, but conflicts with the current state of the object.

Error Code	Triggered When	Applies To
`ALREADY_DELETED`	The object has already been deleted.	Delete
`NOT_DELETED`	The object has not been deleted, so there is nothing to restore.	Restore
`DUPLICATE_VALUE`	A field that must be unique already exists on another object. For example, a `sku` that is already in use.	Store, Update

415 Unsupported Media Type

Error Code	Triggered When	Applies To
`UNSUPPORTED_MEDIA_TYPE`	The `Content-Type` header is not `application/json`.	List, Store, Update

422 Unprocessable Entity

The request is well formed, but the values in item are not valid.

Error Code	Triggered When	Applies To
`VALIDATION_FAILED`	A field required by the layout is missing, a value has the wrong type, or a value is out of range.	Store, Update
`UNKNOWN_FIELD`	`item` contains a field that is not defined by the layout.	Store, Update
`SYSTEM_FIELD_NOT_ALLOWED`	`item` includes a system field: `id`, `created_at`, `updated_at`, `deleted_at`, `author_id` or `group_id`.	Store, Update
`INVALID_RELATION`	A select or relation field, such as `category`, references an ID that does not exist.	Store, Update

429 Too Many Requests

Error Code	Triggered When	Applies To
`RATE_LIMITED`	Too many requests have been sent in a given period. The response includes a `Retry-After` header.	All endpoints

500 Internal Server Error

Error Code	Triggered When	Applies To
`INTERNAL_ERROR`	An unexpected server failure occurred.	All endpoints

503 Service Unavailable

Error Code	Triggered When	Applies To
`SERVICE_UNAVAILABLE`	The database or another dependency is unavailable.	All endpoints

Errors by Endpoint

A summary of which errors each endpoint can return.

Error	View	List	Store	Update	Restore	Delete
`400` `MALFORMED_REQUEST`		✓	✓	✓
`400` `INVALID_PARAMETER`	✓			✓	✓	✓
`400` `MISSING_REQUIRED_PARAMETER`		✓	✓	✓
`400` `INVALID_PAGINATION`		✓
`400` `INVALID_FILTER`		✓
`400` `INVALID_ORDERING`		✓
`401` `UNAUTHENTICATED`	✓	✓	✓	✓	✓	✓
`403` `FORBIDDEN`	✓	✓	✓	✓	✓	✓
`404` `CONTENT_TYPE_NOT_FOUND`	✓	✓	✓	✓	✓	✓
`404` `OBJECT_NOT_FOUND`	✓			✓	✓	✓
`404` `LAYOUT_NOT_FOUND`	✓	✓	✓	✓
`405` `METHOD_NOT_ALLOWED`	✓	✓	✓	✓	✓	✓
`409` `ALREADY_DELETED`						✓
`409` `NOT_DELETED`					✓
`409` `DUPLICATE_VALUE`			✓	✓
`415` `UNSUPPORTED_MEDIA_TYPE`		✓	✓	✓
`422` `VALIDATION_FAILED`			✓	✓
`422` `UNKNOWN_FIELD`			✓	✓
`422` `SYSTEM_FIELD_NOT_ALLOWED`			✓	✓
`422` `INVALID_RELATION`			✓	✓
`429` `RATE_LIMITED`	✓	✓	✓	✓	✓	✓
`500` `INTERNAL_ERROR`	✓	✓	✓	✓	✓	✓
`503` `SERVICE_UNAVAILABLE`	✓	✓	✓	✓	✓	✓

Example Responses

Object not found

Returned when requesting an object that does not exist.

Request

curl -X GET "https://api.example.com/products/999" \
    -H "Authorization: Bearer YOUR_TOKEN"

Response

Status: 404 Not Found

{
    "success": false,
    "error": {
        "code": "OBJECT_NOT_FOUND",
        "message": "No object with id 999 exists for content type 'products'."
    }
}

Validation failure

Returned when the item does not satisfy the layout. Each problem is listed in details.

Request

curl -X POST "https://api.example.com/products/store" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -d '{
        "layout": 1,
        "item": {
            "price": "free"
        }
    }'

Response

Status: 422 Unprocessable Entity

{
    "success": false,
    "error": {
        "code": "VALIDATION_FAILED",
        "message": "One or more fields are invalid.",
        "details": [
            {
                "field": "name",
                "message": "This field is required."
            },
            {
                "field": "price",
                "message": "Must be a number."
            }
        ]
    }
}

Invalid filter

Returned when a filter value does not suit its operator.

Request

curl -X POST "https://api.example.com/products" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -d '{
        "page": 1,
        "pageSize": 10,
        "filters": [
            {
                "field": "price",
                "filter": "BETWEEN",
                "value": 10
            }
        ]
    }'

Response

Status: 400 Bad Request

{
    "success": false,
    "error": {
        "code": "INVALID_FILTER",
        "message": "Filter 'BETWEEN' requires an array of exactly two values.",
        "details": [
            {
                "field": "price",
                "message": "Expected [min, max]."
            }
        ]
    }
}

Restoring an object that is not deleted

Returned when restoring an object that has not been deleted.

Request

curl -X POST "https://api.example.com/products/1/restore" \
    -H "Authorization: Bearer YOUR_TOKEN"

Response

Status: 409 Conflict

{
    "success": false,
    "error": {
        "code": "NOT_DELETED",
        "message": "Object 1 has not been deleted and cannot be restored."
    }
}

Missing or invalid token

Returned when the bearer token is missing, invalid or expired.

Response

Status: 401 Unauthorized

{
    "success": false,
    "error": {
        "code": "UNAUTHENTICATED",
        "message": "A valid bearer token is required."
    }
}

Rate limited

Returned when too many requests have been sent. The Retry-After header gives the number of seconds to wait before retrying.

Response

Status: 429 Too Many Requests

Headers: Retry-After: 30

{
    "success": false,
    "error": {
        "code": "RATE_LIMITED",
        "message": "Too many requests. Try again later."
    }
}

Notes

Errors are uniform. Every error response uses the same success, error.code, error.message and optional error.details structure.
Use error.code in client code. The message text is intended for humans and may change.
details is optional. It is mainly returned with 400 and 422 responses to identify the fields at fault.
System fields are rejected. Sending id, created_at, updated_at, deleted_at, author_id or group_id in item returns SYSTEM_FIELD_NOT_ALLOWED.
Required fields apply to updates too. Partial updates are supported, but any field required by the layout must still be present, otherwise VALIDATION_FAILED is returned.
Only deleted objects can be restored. Restoring an object that is not deleted returns NOT_DELETED.
Deleted objects cannot be deleted again. Deleting an object that is already deleted returns ALREADY_DELETED.
Status codes and error codes are suggestions. Confirm them against your implementation before publishing.