Get relationship

Returns a single relationship by its ID.

Path Parameters
subKey string — REQUIRED

Subscribe key identifying the keyset.

relationshipId string — REQUIRED

ID of the relationship.

Query Parameters
auth string

Required unless you supply signature instead. An Access Manager token authorizing the operation. Use this for client-side callers.

Supply either auth or signature, never both. Supplying neither returns 401 (DS-0203). Supplying both returns 403 (DS-0201).

If the token cannot be decoded, or its projection does not permit the requested fields, the request fails with 403 (DS-0202, INVALID_TOKEN).

signature string

Required unless you supply auth instead. A signature proving the request was signed with the secret key for this keyset. Use this for server-side callers.

Supply either signature or auth, never both. Supplying neither returns 401 (DS-0203). Supplying both returns 403 (DS-0201).

Refer to Signature generation for how to compute it.

Responses
200

Successful response

Schema — OPTIONAL
data object

Relationship record between two entities.

entityAId string

Possible values: 1 ≤ length ≤ 255, Value must match regular expression ^[^,:\*\/\\\s\x00-\x1f\x7f]+$

First entity ID

entityBId string

Possible values: 1 ≤ length ≤ 255, Value must match regular expression ^[^,:\*\/\\\s\x00-\x1f\x7f]+$

Second entity ID

payload objectNode — OPTIONAL
relationshipClass string — OPTIONAL

Possible values: 1 ≤ length ≤ 128, Value must match regular expression ^[a-zA-Z][a-zA-Z0-9_-]*$

Name of the relationship class.

relationshipClassVersion integer — OPTIONAL

Possible values: 1 ≤ value

Version of the relationship class.

id string — OPTIONAL

Possible values: 1 ≤ length ≤ 255

createdAt date-time — OPTIONAL

Date and time the entity was created.

updatedAt date-time

Date and time the entity was last updated.

eTag string

The entity's content fingerprint used in conditional requests.

status string — OPTIONAL

Possible values: 1 ≤ length ≤ 100

Entity status

expiresAt date-time

Date and time when the entity expires (will be deleted automatically).

meta object — OPTIONAL

Cursor-based pagination metadata

next_cursor string — OPTIONAL

Opaque cursor for the next page. Base64-encoded token. Use this value in the cursor query parameter to fetch the next page. Null if there are no more results (has_next is false).

has_next boolean

Indicates whether there are more results after this page

limit integer — OPTIONAL

The limit applied to this page (may differ from requested limit)

400

Bad request.

CodeConstantCause
DS-0002
BAD_REQUEST
Required header or query parameter missing.
DS-0004
VALIDATION_ERROR
Path variable or query parameter failed validation. One error item per violation.
DS-0006
INVALID_ARGUMENT
A parameter value could not be used (wrong type, unusable value).
Schema — OPTIONAL
errors object[] — OPTIONAL
errorCode string

A machine-readable error code. Stable across releases - use this, not message, for programmatic branching. The HTTP status for a given code is fixed.

Codes are grouped by range. Not every code can occur on every operation; each response documents the subset it can return.

Generic

CodeConstantStatusMeaning
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, 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-0010
NOT_ACCEPTABLE
406
Reserved - not currently emitted. 406 responses carry a text/plain body with no error code.
DS-0011
METHOD_NOT_ALLOWED
405
HTTP method not supported for this path.

Resource (01xx)

CodeConstantStatusMeaning
DS-0100
NOT_FOUND
404
The addressed resource does not exist.

Authorization (02xx)

CodeConstantStatusMeaning
DS-0200
DATASYNC_NOT_ENABLED
403
Datasync is not enabled for this subscribe key.
DS-0201
ACCESS_DENIED
403
Access Manager not enabled, conflicting credentials supplied, or authorization check denied.
DS-0202
INVALID_TOKEN
403
The auth PAM token could not be decoded, or its projection does not permit the requested fields.
DS-0203
UNAUTHENTICATED
401
No credentials supplied.

State (03xx)

CodeConstantStatusMeaning
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.

Size limits (04xx)

CodeConstantStatusMeaning
DS-0400
CONTENT_TOO_LARGE
413
Reserved - not currently emitted.

Custom fields (05xx)

CodeConstantStatusMeaning
DS-0500
CUSTOM_NOT_SCALAR
400
Reserved - not currently emitted.

Configuration (06xx)

CodeConstantStatusMeaning
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.

Patch (07xx)

CodeConstantStatusMeaning
DS-0700
IMMUTABLE_FIELD_MODIFICATION
400
A patch targets a pointer outside the mutable set. Patch only.

Relationships (08xx)

CodeConstantStatusMeaning
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.

Class management (09xx)

CodeConstantStatusMeaning
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-0904
MISSING_PARENT_PROPERTY
400
Reserved - not currently emitted. Missing parent properties are inherited automatically.
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 record field (id, createdAt, updatedAt, status). Only status may be re-declared, and only as {name: "status", path: "/status"} to control its projections.
message string

A human-readable description of the error, intended for logs and diagnostics. Not stable across releases - do not parse or branch on it.

path string — OPTIONAL

Location of the input that caused the error. Present only for codes that can identify one. The form depends on the code: a JSON Pointer into the request payload (DS-0008, DS-0602, DS-0650), a query parameter name (filter for DS-0005, sort for DS-0006), a field name (DS-0004), or a class property name (DS-0903).

401

Unauthorized - no usable credentials were supplied.

CodeConstantCause
DS-0203
UNAUTHENTICATED
Neither a PAM token (auth) nor a request signature was supplied, or the portal session token is missing.
Schema — OPTIONAL
errors object[] — OPTIONAL
errorCode string

A machine-readable error code. Stable across releases - use this, not message, for programmatic branching. The HTTP status for a given code is fixed.

Codes are grouped by range. Not every code can occur on every operation; each response documents the subset it can return.

Generic

CodeConstantStatusMeaning
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, 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-0010
NOT_ACCEPTABLE
406
Reserved - not currently emitted. 406 responses carry a text/plain body with no error code.
DS-0011
METHOD_NOT_ALLOWED
405
HTTP method not supported for this path.

Resource (01xx)

CodeConstantStatusMeaning
DS-0100
NOT_FOUND
404
The addressed resource does not exist.

Authorization (02xx)

CodeConstantStatusMeaning
DS-0200
DATASYNC_NOT_ENABLED
403
Datasync is not enabled for this subscribe key.
DS-0201
ACCESS_DENIED
403
Access Manager not enabled, conflicting credentials supplied, or authorization check denied.
DS-0202
INVALID_TOKEN
403
The auth PAM token could not be decoded, or its projection does not permit the requested fields.
DS-0203
UNAUTHENTICATED
401
No credentials supplied.

State (03xx)

CodeConstantStatusMeaning
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.

Size limits (04xx)

CodeConstantStatusMeaning
DS-0400
CONTENT_TOO_LARGE
413
Reserved - not currently emitted.

Custom fields (05xx)

CodeConstantStatusMeaning
DS-0500
CUSTOM_NOT_SCALAR
400
Reserved - not currently emitted.

Configuration (06xx)

CodeConstantStatusMeaning
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.

Patch (07xx)

CodeConstantStatusMeaning
DS-0700
IMMUTABLE_FIELD_MODIFICATION
400
A patch targets a pointer outside the mutable set. Patch only.

Relationships (08xx)

CodeConstantStatusMeaning
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.

Class management (09xx)

CodeConstantStatusMeaning
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-0904
MISSING_PARENT_PROPERTY
400
Reserved - not currently emitted. Missing parent properties are inherited automatically.
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 record field (id, createdAt, updatedAt, status). Only status may be re-declared, and only as {name: "status", path: "/status"} to control its projections.
message string

A human-readable description of the error, intended for logs and diagnostics. Not stable across releases - do not parse or branch on it.

path string — OPTIONAL

Location of the input that caused the error. Present only for codes that can identify one. The form depends on the code: a JSON Pointer into the request payload (DS-0008, DS-0602, DS-0650), a query parameter name (filter for DS-0005, sort for DS-0006), a field name (DS-0004), or a class property name (DS-0903).

403

Forbidden - credentials were recognised but the request is not permitted.

CodeConstantCause
DS-0200
DATASYNC_NOT_ENABLED
Datasync is not enabled for this subscribe key.
DS-0201
ACCESS_DENIED
Access Manager is not enabled for the keyset, auth and signature were both supplied, or the portal authorization check denied the request.
DS-0202
INVALID_TOKEN
The auth PAM token could not be decoded, or its projection does not permit the requested fields.
Schema — OPTIONAL
errors object[] — OPTIONAL
errorCode string

A machine-readable error code. Stable across releases - use this, not message, for programmatic branching. The HTTP status for a given code is fixed.

Codes are grouped by range. Not every code can occur on every operation; each response documents the subset it can return.

Generic

CodeConstantStatusMeaning
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, 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-0010
NOT_ACCEPTABLE
406
Reserved - not currently emitted. 406 responses carry a text/plain body with no error code.
DS-0011
METHOD_NOT_ALLOWED
405
HTTP method not supported for this path.

Resource (01xx)

CodeConstantStatusMeaning
DS-0100
NOT_FOUND
404
The addressed resource does not exist.

Authorization (02xx)

CodeConstantStatusMeaning
DS-0200
DATASYNC_NOT_ENABLED
403
Datasync is not enabled for this subscribe key.
DS-0201
ACCESS_DENIED
403
Access Manager not enabled, conflicting credentials supplied, or authorization check denied.
DS-0202
INVALID_TOKEN
403
The auth PAM token could not be decoded, or its projection does not permit the requested fields.
DS-0203
UNAUTHENTICATED
401
No credentials supplied.

State (03xx)

CodeConstantStatusMeaning
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.

Size limits (04xx)

CodeConstantStatusMeaning
DS-0400
CONTENT_TOO_LARGE
413
Reserved - not currently emitted.

Custom fields (05xx)

CodeConstantStatusMeaning
DS-0500
CUSTOM_NOT_SCALAR
400
Reserved - not currently emitted.

Configuration (06xx)

CodeConstantStatusMeaning
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.

Patch (07xx)

CodeConstantStatusMeaning
DS-0700
IMMUTABLE_FIELD_MODIFICATION
400
A patch targets a pointer outside the mutable set. Patch only.

Relationships (08xx)

CodeConstantStatusMeaning
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.

Class management (09xx)

CodeConstantStatusMeaning
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-0904
MISSING_PARENT_PROPERTY
400
Reserved - not currently emitted. Missing parent properties are inherited automatically.
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 record field (id, createdAt, updatedAt, status). Only status may be re-declared, and only as {name: "status", path: "/status"} to control its projections.
message string

A human-readable description of the error, intended for logs and diagnostics. Not stable across releases - do not parse or branch on it.

path string — OPTIONAL

Location of the input that caused the error. Present only for codes that can identify one. The form depends on the code: a JSON Pointer into the request payload (DS-0008, DS-0602, DS-0650), a query parameter name (filter for DS-0005, sort for DS-0006), a field name (DS-0004), or a class property name (DS-0903).

404

Not found.

CodeConstantCause
DS-0100
NOT_FOUND
The addressed resource does not exist. Also returned when a conditional request supplies no If-Match and the resource is absent.
DS-0600
CONFIG_NOT_FOUND
The subscribe key is unknown to the configuration service, or its datasync region is not configured.
Schema — OPTIONAL
errors object[] — OPTIONAL
errorCode string

A machine-readable error code. Stable across releases - use this, not message, for programmatic branching. The HTTP status for a given code is fixed.

Codes are grouped by range. Not every code can occur on every operation; each response documents the subset it can return.

Generic

CodeConstantStatusMeaning
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, 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-0010
NOT_ACCEPTABLE
406
Reserved - not currently emitted. 406 responses carry a text/plain body with no error code.
DS-0011
METHOD_NOT_ALLOWED
405
HTTP method not supported for this path.

Resource (01xx)

CodeConstantStatusMeaning
DS-0100
NOT_FOUND
404
The addressed resource does not exist.

Authorization (02xx)

CodeConstantStatusMeaning
DS-0200
DATASYNC_NOT_ENABLED
403
Datasync is not enabled for this subscribe key.
DS-0201
ACCESS_DENIED
403
Access Manager not enabled, conflicting credentials supplied, or authorization check denied.
DS-0202
INVALID_TOKEN
403
The auth PAM token could not be decoded, or its projection does not permit the requested fields.
DS-0203
UNAUTHENTICATED
401
No credentials supplied.

State (03xx)

CodeConstantStatusMeaning
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.

Size limits (04xx)

CodeConstantStatusMeaning
DS-0400
CONTENT_TOO_LARGE
413
Reserved - not currently emitted.

Custom fields (05xx)

CodeConstantStatusMeaning
DS-0500
CUSTOM_NOT_SCALAR
400
Reserved - not currently emitted.

Configuration (06xx)

CodeConstantStatusMeaning
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.

Patch (07xx)

CodeConstantStatusMeaning
DS-0700
IMMUTABLE_FIELD_MODIFICATION
400
A patch targets a pointer outside the mutable set. Patch only.

Relationships (08xx)

CodeConstantStatusMeaning
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.

Class management (09xx)

CodeConstantStatusMeaning
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-0904
MISSING_PARENT_PROPERTY
400
Reserved - not currently emitted. Missing parent properties are inherited automatically.
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 record field (id, createdAt, updatedAt, status). Only status may be re-declared, and only as {name: "status", path: "/status"} to control its projections.
message string

A human-readable description of the error, intended for logs and diagnostics. Not stable across releases - do not parse or branch on it.

path string — OPTIONAL

Location of the input that caused the error. Present only for codes that can identify one. The form depends on the code: a JSON Pointer into the request payload (DS-0008, DS-0602, DS-0650), a query parameter name (filter for DS-0005, sort for DS-0006), a field name (DS-0004), or a class property name (DS-0903).

406

Not Acceptable - the Accept header does not contain a supported value.

This response carries a text/plain body and no error code.

Schema — OPTIONAL
string
429

Too Many Requests - rate limit exceeded.

Rate limiting is applied by the edge in front of this service; the service itself defines no error code for this status. Clients should not rely on an error code being present.

Schema — OPTIONAL
errors object[] — OPTIONAL
errorCode string

A machine-readable error code. Stable across releases - use this, not message, for programmatic branching. The HTTP status for a given code is fixed.

Codes are grouped by range. Not every code can occur on every operation; each response documents the subset it can return.

Generic

CodeConstantStatusMeaning
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, 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-0010
NOT_ACCEPTABLE
406
Reserved - not currently emitted. 406 responses carry a text/plain body with no error code.
DS-0011
METHOD_NOT_ALLOWED
405
HTTP method not supported for this path.

Resource (01xx)

CodeConstantStatusMeaning
DS-0100
NOT_FOUND
404
The addressed resource does not exist.

Authorization (02xx)

CodeConstantStatusMeaning
DS-0200
DATASYNC_NOT_ENABLED
403
Datasync is not enabled for this subscribe key.
DS-0201
ACCESS_DENIED
403
Access Manager not enabled, conflicting credentials supplied, or authorization check denied.
DS-0202
INVALID_TOKEN
403
The auth PAM token could not be decoded, or its projection does not permit the requested fields.
DS-0203
UNAUTHENTICATED
401
No credentials supplied.

State (03xx)

CodeConstantStatusMeaning
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.

Size limits (04xx)

CodeConstantStatusMeaning
DS-0400
CONTENT_TOO_LARGE
413
Reserved - not currently emitted.

Custom fields (05xx)

CodeConstantStatusMeaning
DS-0500
CUSTOM_NOT_SCALAR
400
Reserved - not currently emitted.

Configuration (06xx)

CodeConstantStatusMeaning
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.

Patch (07xx)

CodeConstantStatusMeaning
DS-0700
IMMUTABLE_FIELD_MODIFICATION
400
A patch targets a pointer outside the mutable set. Patch only.

Relationships (08xx)

CodeConstantStatusMeaning
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.

Class management (09xx)

CodeConstantStatusMeaning
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-0904
MISSING_PARENT_PROPERTY
400
Reserved - not currently emitted. Missing parent properties are inherited automatically.
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 record field (id, createdAt, updatedAt, status). Only status may be re-declared, and only as {name: "status", path: "/status"} to control its projections.
message string

A human-readable description of the error, intended for logs and diagnostics. Not stable across releases - do not parse or branch on it.

path string — OPTIONAL

Location of the input that caused the error. Present only for codes that can identify one. The form depends on the code: a JSON Pointer into the request payload (DS-0008, DS-0602, DS-0650), a query parameter name (filter for DS-0005, sort for DS-0006), a field name (DS-0004), or a class property name (DS-0903).

500

Internal server error.

CodeConstantCause
DS-0000
INTERNAL_SERVER_ERROR
An unhandled error occurred, or the request could not be routed because of a server-side configuration problem.
Schema — OPTIONAL
errors object[] — OPTIONAL
errorCode string

A machine-readable error code. Stable across releases - use this, not message, for programmatic branching. The HTTP status for a given code is fixed.

Codes are grouped by range. Not every code can occur on every operation; each response documents the subset it can return.

Generic

CodeConstantStatusMeaning
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, 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-0010
NOT_ACCEPTABLE
406
Reserved - not currently emitted. 406 responses carry a text/plain body with no error code.
DS-0011
METHOD_NOT_ALLOWED
405
HTTP method not supported for this path.

Resource (01xx)

CodeConstantStatusMeaning
DS-0100
NOT_FOUND
404
The addressed resource does not exist.

Authorization (02xx)

CodeConstantStatusMeaning
DS-0200
DATASYNC_NOT_ENABLED
403
Datasync is not enabled for this subscribe key.
DS-0201
ACCESS_DENIED
403
Access Manager not enabled, conflicting credentials supplied, or authorization check denied.
DS-0202
INVALID_TOKEN
403
The auth PAM token could not be decoded, or its projection does not permit the requested fields.
DS-0203
UNAUTHENTICATED
401
No credentials supplied.

State (03xx)

CodeConstantStatusMeaning
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.

Size limits (04xx)

CodeConstantStatusMeaning
DS-0400
CONTENT_TOO_LARGE
413
Reserved - not currently emitted.

Custom fields (05xx)

CodeConstantStatusMeaning
DS-0500
CUSTOM_NOT_SCALAR
400
Reserved - not currently emitted.

Configuration (06xx)

CodeConstantStatusMeaning
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.

Patch (07xx)

CodeConstantStatusMeaning
DS-0700
IMMUTABLE_FIELD_MODIFICATION
400
A patch targets a pointer outside the mutable set. Patch only.

Relationships (08xx)

CodeConstantStatusMeaning
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.

Class management (09xx)

CodeConstantStatusMeaning
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-0904
MISSING_PARENT_PROPERTY
400
Reserved - not currently emitted. Missing parent properties are inherited automatically.
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 record field (id, createdAt, updatedAt, status). Only status may be re-declared, and only as {name: "status", path: "/status"} to control its projections.
message string

A human-readable description of the error, intended for logs and diagnostics. Not stable across releases - do not parse or branch on it.

path string — OPTIONAL

Location of the input that caused the error. Present only for codes that can identify one. The form depends on the code: a JSON Pointer into the request payload (DS-0008, DS-0602, DS-0650), a query parameter name (filter for DS-0005, sort for DS-0006), a field name (DS-0004), or a class property name (DS-0903).

503

Service Unavailable.

CodeConstantCause
DS-0009
SERVICE_UNAVAILABLE
A dependency required to serve the request is unavailable, or the request could not be forwarded to its target region. A Retry-After header may be present.
Schema — OPTIONAL
errors object[] — OPTIONAL
errorCode string

A machine-readable error code. Stable across releases - use this, not message, for programmatic branching. The HTTP status for a given code is fixed.

Codes are grouped by range. Not every code can occur on every operation; each response documents the subset it can return.

Generic

CodeConstantStatusMeaning
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, 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-0010
NOT_ACCEPTABLE
406
Reserved - not currently emitted. 406 responses carry a text/plain body with no error code.
DS-0011
METHOD_NOT_ALLOWED
405
HTTP method not supported for this path.

Resource (01xx)

CodeConstantStatusMeaning
DS-0100
NOT_FOUND
404
The addressed resource does not exist.

Authorization (02xx)

CodeConstantStatusMeaning
DS-0200
DATASYNC_NOT_ENABLED
403
Datasync is not enabled for this subscribe key.
DS-0201
ACCESS_DENIED
403
Access Manager not enabled, conflicting credentials supplied, or authorization check denied.
DS-0202
INVALID_TOKEN
403
The auth PAM token could not be decoded, or its projection does not permit the requested fields.
DS-0203
UNAUTHENTICATED
401
No credentials supplied.

State (03xx)

CodeConstantStatusMeaning
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.

Size limits (04xx)

CodeConstantStatusMeaning
DS-0400
CONTENT_TOO_LARGE
413
Reserved - not currently emitted.

Custom fields (05xx)

CodeConstantStatusMeaning
DS-0500
CUSTOM_NOT_SCALAR
400
Reserved - not currently emitted.

Configuration (06xx)

CodeConstantStatusMeaning
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.

Patch (07xx)

CodeConstantStatusMeaning
DS-0700
IMMUTABLE_FIELD_MODIFICATION
400
A patch targets a pointer outside the mutable set. Patch only.

Relationships (08xx)

CodeConstantStatusMeaning
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.

Class management (09xx)

CodeConstantStatusMeaning
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-0904
MISSING_PARENT_PROPERTY
400
Reserved - not currently emitted. Missing parent properties are inherited automatically.
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 record field (id, createdAt, updatedAt, status). Only status may be re-declared, and only as {name: "status", path: "/status"} to control its projections.
message string

A human-readable description of the error, intended for logs and diagnostics. Not stable across releases - do not parse or branch on it.

path string — OPTIONAL

Location of the input that caused the error. Present only for codes that can identify one. The form depends on the code: a JSON Pointer into the request payload (DS-0008, DS-0602, DS-0650), a query parameter name (filter for DS-0005, sort for DS-0006), a field name (DS-0004), or a class property name (DS-0903).

* required
subKey*
Type: string
Subscribe key identifying the keyset.
relationshipId*
Type: string
ID of the relationship.
auth
Type: string
Required unless you supply signature instead. An Access Manager token authorizing the operation. Use this for client-side callers.

Supply either auth or signature, never both. Supplying neither returns 401 (DS-0203). Supplying both returns 403 (DS-0201).

If the token cannot be decoded, or its projection does not permit the requested fields, the request fails with 403 (DS-0202, INVALID_TOKEN).
signature
Type: string
Required unless you supply auth instead. A signature proving the request was signed with the secret key for this keyset. Use this for server-side callers.

Supply either signature or auth, never both. Supplying neither returns 401 (DS-0203). Supplying both returns 403 (DS-0201).

Refer to Signature generation for how to compute it.
Bad request.
CodeConstantCause
DS-0002BAD_REQUESTRequired header or query parameter missing.
DS-0004VALIDATION_ERRORPath variable or query parameter failed validation. One error item per violation.
DS-0006INVALID_ARGUMENTA parameter value could not be used (wrong type, unusable value).
errors
Type: array
Array items:
items
Type: object
Error object
Example Response
{
  "errors": [
    {
      "errorCode": "DS-0002",
      "message": "Required request parameter 'relationship_class' is missing"
    }
  ]
}
Unauthorized - no usable credentials were supplied.
CodeConstantCause
DS-0203UNAUTHENTICATEDNeither a PAM token (auth) nor a request signature was supplied, or the portal session token is missing.
errors
Type: array
Array items:
items
Type: object
Error object
Example Response
{
  "errors": [
    {
      "errorCode": "DS-0203",
      "message": "Authentication required: provide either a PAM token via 'auth' parameter or a request signature."
    }
  ]
}
Forbidden - credentials were recognised but the request is not permitted.
CodeConstantCause
DS-0200DATASYNC_NOT_ENABLEDDatasync is not enabled for this subscribe key.
DS-0201ACCESS_DENIEDAccess Manager is not enabled for the keyset, auth and signature were both supplied, or the portal authorization check denied the request.
DS-0202INVALID_TOKENThe auth PAM token could not be decoded, or its projection does not permit the requested fields.
errors
Type: array
Array items:
items
Type: object
Error object
Example Response
{
  "errors": [
    {
      "errorCode": "DS-0200",
      "message": "Datasync not enabled for this subscribe key"
    }
  ]
}
Not found.
CodeConstantCause
DS-0100NOT_FOUNDThe addressed resource does not exist. Also returned when a conditional request supplies no If-Match and the resource is absent.
DS-0600CONFIG_NOT_FOUNDThe subscribe key is unknown to the configuration service, or its datasync region is not configured.
errors
Type: array
Array items:
items
Type: object
Error object
Example Response
{
  "errors": [
    {
      "errorCode": "DS-0100",
      "message": "Entity not found: user-42"
    }
  ]
}
Not Acceptable - the Accept header does not contain a supported value.

This response carries a text/plain body and no error code.
Too Many Requests - rate limit exceeded.

Rate limiting is applied by the edge in front of this service; the service itself defines no
error code for this status. Clients should not rely on an error code being present.
errors
Type: array
Array items:
items
Type: object
Error object
Internal server error.
CodeConstantCause
DS-0000INTERNAL_SERVER_ERRORAn unhandled error occurred, or the request could not be routed because of a server-side configuration problem.
errors
Type: array
Array items:
items
Type: object
Error object
Example Response
{
  "errors": [
    {
      "errorCode": "DS-0000",
      "message": "Internal server error"
    }
  ]
}
Service Unavailable.
CodeConstantCause
DS-0009SERVICE_UNAVAILABLEA dependency required to serve the request is unavailable, or the request could not be forwarded to its target region. A Retry-After header may be present.
errors
Type: array
Array items:
items
Type: object
Error object
Example Response
{
  "errors": [
    {
      "errorCode": "DS-0009",
      "message": "Service temporarily unavailable"
    }
  ]
}