---
source_url: https://www.pubnub.com/docs/data-storage/structured-data/error-codes
title: DataSync error codes
updated_at: 2026-09-30T07:20:08.000Z
---

# DataSync error codes

## Documentation index

To discover more PubNub resources:

1. Fetch [PubNub's llms.txt](https://www.pubnub.com/llms-full.txt) for a list of available pages in Markdown format.
2. Identify relevant URLs from that index.
3. Fetch the target pages.

Do not assume a path exists, always check the index first.

Every DataSync error response uses the same envelope. The `errorCode` field is the stable programmatic identifier; don't rely on the `message` text, which can change.

## Error envelope

```json
{
  "errors": [
    { "errorCode": "DS-0650", "message": "...", "path": "..." }
  ]
}
```

A validation failure can return more than one error object. The `path` field appears only on codes that point at a specific input. Its form follows the code: a JSON Pointer into the request payload, a query parameter name, a field name, or a class property name.

Every DataSync error code carries the `DS-` prefix. Refer to the Responses section on any endpoint for the exact codes it can return, for example [Create entity](https://www.pubnub.com/docs/sdks/rest-api/create-entity.md).

## HTTP status codes

| Condition | HTTP status |
| --- | --- |
| No credential supplied | 401 |
| An expired, revoked, malformed, or otherwise unauthorized token | 403 |
| A projection name that doesn't exist on the class | 403 |
| A write outside the token's resolved projection | 403 |
| Modifying a Global class definition (for example `User`, `Channel`, or `Membership`) | 403 |
| DataSync not enabled on the keyset | 403 |
| An object `id` that doesn't exist on get, replace, partial update, or delete | 404 |
| A class or specific class version that doesn't exist on create | 404 |
| A relationship or membership endpoint where a linked entity doesn't exist | 404 |
| An unknown subscribe key | 404 |
| An `id` that already exists on create | 409 |
| A relationship that would violate its class's cardinality | 409 |
| Deleting a class version that another class extends | 409 |
| A stale `eTag` on `If-Match` | 412 |
| A `PATCH` that touches any path other than `/status`, the class version, or `/payload` and its children | 400 |
| A payload that fails a declared property's type or nullability check | 400 |
| Both `filter_fast` and `filter` on one request | 400 |
| A malformed filter expression, or more predicates than the limit allows | 400 |
| Sorting by a property that isn't sortable in that context, or an invalid cursor | 400 |
| Malformed JSON in the request body | 400 |
| An unsupported `Content-Type` | 415 |
| An `Accept` header DataSync can't satisfy | 406 |
| A class property named `id`, `createdAt`, or `updatedAt`, or a `status` property at any path other than `/status` | 400 (`DS-0906`) |

## DS- error codes

| Code | Constant | HTTP status | Meaning |
| --- | --- | --- | --- |
| `DS-0000` | `INTERNAL_SERVER_ERROR` | 500 | Unhandled server error, or a server-side routing configuration problem. |
| `DS-0002` | `BAD_REQUEST` | 400 | Required header or query parameter missing, or request input otherwise unusable. |
| `DS-0003` | `INVALID_JSON` | 400 | Request body absent, empty, or not valid JSON. |
| `DS-0004` | `VALIDATION_ERROR` | 400 | Body, path variable, or query parameter failed validation. One error item per violation. |
| `DS-0005` | `INVALID_FILTER` | 400 | `filter_fast` / `filter` could not be parsed or validated. |
| `DS-0006` | `INVALID_ARGUMENT` | 400 | An argument could not be used: a sort field that is not sortable in that request, undecodable cursor, malformed JSON Pointer, or parameter type mismatch. |
| `DS-0007` | `UNSUPPORTED_CONTENT_TYPE` | 415 | Request `Content-Type` not supported. |
| `DS-0008` | `UNEXPECTED_FILTERABLE_FIELD_VALUE` | 400 | A declared class property's value does not match its `valueKind`. |
| `DS-0009` | `SERVICE_UNAVAILABLE` | 503 | A required dependency is unavailable, or the request could not be forwarded to its region. |
| `DS-0011` | `METHOD_NOT_ALLOWED` | 405 | HTTP method not supported for this path. |
| `DS-0100` | `NOT_FOUND` | 404 | The addressed resource does not exist. |
| `DS-0200` | `DATASYNC_NOT_ENABLED` | 403 | DataSync is not enabled for this subscribe key. |
| `DS-0201` | `ACCESS_DENIED` | 403 | [Access Manager](https://www.pubnub.com/docs/security/access-control/overview.md) not enabled, conflicting credentials supplied, or authorization check denied. |
| `DS-0202` | `INVALID_TOKEN` | 403 | The auth token could not be decoded, its projection does not permit the requested fields, or one of its grant patterns is too complex to evaluate. |
| `DS-0203` | `UNAUTHENTICATED` | 401 | No credentials supplied. |
| `DS-0300` | `ETAG_MISMATCH` | 412 | `If-Match` does not contain the resource's current `eTag`. |
| `DS-0301` | `CONFLICT` | 409 | A resource with the same identity already exists. |
| `DS-0600` | `CONFIG_NOT_FOUND` | 404 | Subscribe key unknown to the configuration service, or its DataSync region is not configured. |
| `DS-0602` | `UNSUPPORTED_ENTITY_PROPERTY_TYPE` | 400 | A declared property's path resolves to a non-scalar node (object or array). |
| `DS-0650` | `NON_NULLABLE_PROPERTY` | 400 | A property declared `nullable: false` is missing or explicitly null. The `path` field points at the property. A non-nullable property at an incorrect JSON Pointer path causes every write for that class to fail with this code. |
| `DS-0700` | `IMMUTABLE_FIELD_MODIFICATION` | 400 | A patch targets a pointer outside the mutable set. Patch only. |
| `DS-0800` | `WRONG_ENTITY_CLASS_TYPE` | 400 | An endpoint entity's class does not satisfy the relationship class for that side. Create only. |
| `DS-0801` | `CARDINALITY_VIOLATED` | 409 | ONE-TO-ONE or ONE-TO-MANY cardinality already satisfied. Create only. |
| `DS-0900` | `GLOBAL_CLASS_MODIFICATION` | 403 | Global class definitions are read-only. Replace and delete only. |
| `DS-0901` | `PROJECTION_LIMIT_EXCEEDED` | 400 | Distinct projections across all properties exceed the per-class maximum. |
| `DS-0902` | `INVALID_PROJECTION_NAME` | 400 | Projection name too long or malformed, or a property declares an empty projection list. |
| `DS-0903` | `INCOMPATIBLE_CHILD_PROPERTY` | 400 | A redeclared inherited property differs from the parent in `path`, `valueKind`, or `nullable`. Entity classes only. |
| `DS-0905` | `CLASS_HAS_CHILDREN` | 409 | The class still has subclasses and cannot be deleted. Entity classes only. |
| `DS-0906` | `RESERVED_PROPERTY_NAME` | 400 | A declared property uses the name of a built-in field (`id`, `createdAt`, `updatedAt`, `status`). Only `status` may be re-declared, and only as `{"name": "status", "path": "/status"}` to control its projections. |

## Notes on 403 responses

The two projection-related 403s (an unknown projection name and a write outside the resolved projection) share one error code and the generic message `Invalid value for 'auth' parameter`. Neither response names the projection or the field involved. That's by design, so the response doesn't disclose which projections or fields exist.

Last updated at: 2026-09-30T07:20:08.000Z