API REFERENCE · Review evidence

Open a review case for an existing retained screening

Complete request parameters, body fields, response formats, examples, and errors for POST /cases.

Base URL: https://www.sanctionskit.com/api/v1. Documentation examples are saved and require no API key to read.

POST/casesOpen a review case for an existing retained screening

Authentication: Authorization: Bearer YOUR_API_KEY (required). Use a server-side key for the intended environment and scopes.

Required API key scope: cases:write. Creates an open case for standard-retention evidence when a case was not already created automatically. Send decision=open; completed decisions require the human investigation workflow and return investigation_review_required. No Idempotency-Key contract applies to this endpoint. Before retrying an uncertain response, query GET /cases?screeningId=...; duplicate creation returns case_exists with error.details.caseId.

Request parameters

Path parameters: None.
Query parameters: None.
Headers: Authorization (required)
JSON body fields: decision, notes, screeningId, expectedUpdatedAt

Send JSON body fields as application/json, not as query parameters. Field definitions and nested properties follow below.

Request body

Required body. JSON properties belong in the request body, separately from headers and URL parameters.

JSON request body. Send Content-Type: application/json with UTF-8 encoding; fields marked required must be present. Omit optional fields unless needed. Null is accepted only where explicitly shown. Unknown properties are rejected for validated request objects. Duplicate keys and nesting beyond 32 levels are rejected. Maximum body size: 1,048,576 bytes (1 MiB).

application/jsonView CaseRequest schema

Request body fields

Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.

Open a case for retained evidence. decision must be open; the API cannot complete the human investigation or independent approval workflow.

decisionRequired

"open"

Must be open when creating a case. Completed decisions require the human investigation workflow and return investigation_review_required here.

Must equal "open".

notesRequired

string

Nonempty opening rationale, trimmed before validation. Retained under the case policy.

Minimum length: 1. Maximum length: 5000.

screeningIdRequired

string

UUID of a retained standard screening in this organization and environment. An existing case returns case_exists; minimal or expired evidence cannot be used.

Format: uuid. Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$.

expectedUpdatedAtOptional

string

Legacy optional timestamp accepted and echoed by creation. It is not a concurrency guard for a new case; omit it.

Format: date-time. Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$.

Additional fields are not accepted.

Example request

{
  "screeningId": "01234567-89ab-4cde-8f01-23456789abcd",
  "decision": "open",
  "notes": "Synthetic screening requires review."
}

Responses

201Successful response. JSON object with the required data key. All properties marked required are present, including keys whose value may be null. Unmarked properties can be omitted; clients should tolerate additional response properties.

Response headers

X-Request-Id

string

Server-generated request correlation identifier.

Format: uuid.

application/json

Response fields

Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.

dataRequired

objectView CaseCreated schema

data fields and rules

data.idRequired: string
Format: uuid.
data.screeningIdRequired: string
Format: uuid.
data.decisionRequired: "open"
Must equal "open".
data.notesRequired: string
data.expectedUpdatedAtOptional: string
Format: date-time.

Example response

Synthetic contract example, validated against the response schema. Invented data; no live customer, provider request, payment, message or source activation.

{
  "data": {
    "id": "01234567-89ab-4cde-8f01-23456789abcd",
    "screeningId": "01234567-89ab-4cde-8f01-23456789abcd",
    "decision": "open",
    "notes": "Synthetic case awaiting identity review."
  }
}

400invalid_request — Correct the request fields, resource identifiers, JSON body or query parameters before retrying.

Response headers

X-Request-Id

string

Server-generated correlation identifier, also returned in error.requestId.

Format: uuid.

application/jsonView Error schema

Response fields

Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.

Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.

errorRequired

object

error fields and rules

error.codeRequired

string

Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.

error.messageRequired

string

Human-readable explanation. Do not parse this text to control application behavior.

error.requestIdRequired

string

Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.

Format: uuid.

error.detailsOptional

object[] or object or string or number or boolean or null

Optional JSON details for client and validation failures. Validation failures return an array of { path, message } issues; other 4xx codes may return a code-specific object. Server failures omit details. Never assume this key is present.

error.details fields and rules

Allowed alternatives

object[]
Maximum items: 50.
Each array item: object.
error.details[].pathRequired
string
Dot-separated invalid field path, including array indexes.
Maximum length: 160.
error.details[].messageRequired
string
Validation problem for this field.
Maximum length: 300.
object
Additional keys are allowed; their values are not a fixed contract.
string or number or boolean or null
May be null.

error.detailsTruncatedOptional

boolean

True when only the first 50 validation issues are returned. Validation paths and messages are bounded.

Example response

Synthetic error example. Correct the request fields, resource identifiers, JSON body or query parameters before retrying.

{
  "error": {
    "code": "invalid_request",
    "message": "The request is invalid.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

401authentication_required — Send Authorization: Bearer with a valid API key. An omitted header can produce authentication_required; invalid supplied credentials produce invalid_api_key. invalid_api_key — Use an active key for the intended environment.

Response headers

X-Request-Id

string

Server-generated correlation identifier, also returned in error.requestId.

Format: uuid.

WWW-Authenticate

string

Bearer authentication challenge.

application/jsonView Error schema

Response fields

Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.

Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.

errorRequired

object

error fields and rules

error.codeRequired

string

Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.

error.messageRequired

string

Human-readable explanation. Do not parse this text to control application behavior.

error.requestIdRequired

string

Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.

Format: uuid.

error.detailsOptional

object[] or object or string or number or boolean or null

error.details fields and rules

Allowed alternatives

object[]
Maximum items: 50.
Each array item: object.
error.details[].pathRequired
string
Dot-separated invalid field path, including array indexes.
Maximum length: 160.
error.details[].messageRequired
string
Validation problem for this field.
Maximum length: 300.
object
Additional keys are allowed; their values are not a fixed contract.
string or number or boolean or null
May be null.

error.detailsTruncatedOptional

boolean

True when only the first 50 validation issues are returned. Validation paths and messages are bounded.

Example response

Synthetic error example. Send Authorization: Bearer with a valid API key. An omitted header can produce authentication_required; invalid supplied credentials produce invalid_api_key.

{
  "error": {
    "code": "authentication_required",
    "message": "Sign in to continue.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

invalid api key

Synthetic error example. Use an active key for the intended environment.

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key is invalid, expired, or revoked.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

403permission_denied — Ask an organization owner to grant the required role or API-key scope. insufficient_scope — Use a key with the scope stated in this operation.

Response headers

X-Request-Id

string

Server-generated correlation identifier, also returned in error.requestId.

Format: uuid.

application/jsonView Error schema

Response fields

Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.

Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.

errorRequired

object

error fields and rules

error.codeRequired

string

Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.

error.messageRequired

string

Human-readable explanation. Do not parse this text to control application behavior.

error.requestIdRequired

string

Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.

Format: uuid.

error.detailsOptional

object[] or object or string or number or boolean or null

error.details fields and rules

Allowed alternatives

object[]
Maximum items: 50.
Each array item: object.
error.details[].pathRequired
string
Dot-separated invalid field path, including array indexes.
Maximum length: 160.
error.details[].messageRequired
string
Validation problem for this field.
Maximum length: 300.
object
Additional keys are allowed; their values are not a fixed contract.
string or number or boolean or null
May be null.

error.detailsTruncatedOptional

boolean

True when only the first 50 validation issues are returned. Validation paths and messages are bounded.

Example response

Synthetic error example. Ask an organization owner to grant the required role or API-key scope.

{
  "error": {
    "code": "permission_denied",
    "message": "Your role does not allow this action.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

insufficient scope

Synthetic error example. Use a key with the scope stated in this operation.

{
  "error": {
    "code": "insufficient_scope",
    "message": "The API key does not grant this action.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

404not_found — Check the identifier and selected environment. The resource must belong to your organization and remain available.

Response headers

X-Request-Id

string

Server-generated correlation identifier, also returned in error.requestId.

Format: uuid.

application/jsonView Error schema

Response fields

Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.

Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.

errorRequired

object

error fields and rules

error.codeRequired

string

Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.

error.messageRequired

string

Human-readable explanation. Do not parse this text to control application behavior.

error.requestIdRequired

string

Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.

Format: uuid.

error.detailsOptional

object[] or object or string or number or boolean or null

error.details fields and rules

Allowed alternatives

object[]
Maximum items: 50.
Each array item: object.
error.details[].pathRequired
string
Dot-separated invalid field path, including array indexes.
Maximum length: 160.
error.details[].messageRequired
string
Validation problem for this field.
Maximum length: 300.
object
Additional keys are allowed; their values are not a fixed contract.
string or number or boolean or null
May be null.

error.detailsTruncatedOptional

boolean

True when only the first 50 validation issues are returned. Validation paths and messages are bounded.

Example response

Synthetic error example. Check the identifier and selected environment. The resource must belong to your organization and remain available.

{
  "error": {
    "code": "not_found",
    "message": "Screening not found.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

405method_not_allowed — Use a method in the Allow response header. OPTIONS lists supported methods; HEAD follows GET authorization and returns no body.

Response headers

X-Request-Id

string

Server-generated correlation identifier, also returned in error.requestId.

Format: uuid.

Allow

string

Comma-separated supported HTTP methods.

application/jsonView Error schema

Response fields

Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.

Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.

errorRequired

object

error fields and rules

error.codeRequired

string

Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.

error.messageRequired

string

Human-readable explanation. Do not parse this text to control application behavior.

error.requestIdRequired

string

Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.

Format: uuid.

error.detailsOptional

object[] or object or string or number or boolean or null

error.details fields and rules

Allowed alternatives

object[]
Maximum items: 50.
Each array item: object.
error.details[].pathRequired
string
Dot-separated invalid field path, including array indexes.
Maximum length: 160.
error.details[].messageRequired
string
Validation problem for this field.
Maximum length: 300.
object
Additional keys are allowed; their values are not a fixed contract.
string or number or boolean or null
May be null.

error.detailsTruncatedOptional

boolean

True when only the first 50 validation issues are returned. Validation paths and messages are bounded.

Example response

Synthetic error example. Use a method in the Allow response header. OPTIONS lists supported methods; HEAD follows GET authorization and returns no body.

{
  "error": {
    "code": "method_not_allowed",
    "message": "This method is not supported for this endpoint.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

408invalid_request — Reconnect and retry using the same idempotency key and identical input where supported.

Response headers

X-Request-Id

string

Server-generated correlation identifier, also returned in error.requestId.

Format: uuid.

application/jsonView Error schema

Response fields

Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.

Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.

errorRequired

object

error fields and rules

error.codeRequired

string

Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.

error.messageRequired

string

Human-readable explanation. Do not parse this text to control application behavior.

error.requestIdRequired

string

Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.

Format: uuid.

error.detailsOptional

object[] or object or string or number or boolean or null

error.details fields and rules

Allowed alternatives

object[]
Maximum items: 50.
Each array item: object.
error.details[].pathRequired
string
Dot-separated invalid field path, including array indexes.
Maximum length: 160.
error.details[].messageRequired
string
Validation problem for this field.
Maximum length: 300.
object
Additional keys are allowed; their values are not a fixed contract.
string or number or boolean or null
May be null.

error.detailsTruncatedOptional

boolean

True when only the first 50 validation issues are returned. Validation paths and messages are bounded.

Example response

Synthetic error example. Reconnect and retry using the same idempotency key and identical input where supported.

{
  "error": {
    "code": "invalid_request",
    "message": "The request body was not received within 10 seconds.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

409investigation_review_required — Use the investigation match-review, submit and approval endpoints before recording a conclusion. case_exists — Open the existing case and append your review there.

Response headers

X-Request-Id

string

Server-generated correlation identifier, also returned in error.requestId.

Format: uuid.

application/jsonView Error schema

Response fields

Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.

Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.

errorRequired

object

error fields and rules

error.codeRequired

string

Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.

error.messageRequired

string

Human-readable explanation. Do not parse this text to control application behavior.

error.requestIdRequired

string

Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.

Format: uuid.

error.detailsOptional

object[] or object or string or number or boolean or null

error.details fields and rules

Allowed alternatives

object[]
Maximum items: 50.
Each array item: object.
error.details[].pathRequired
string
Dot-separated invalid field path, including array indexes.
Maximum length: 160.
error.details[].messageRequired
string
Validation problem for this field.
Maximum length: 300.
object
Additional keys are allowed; their values are not a fixed contract.
string or number or boolean or null
May be null.

error.detailsTruncatedOptional

boolean

True when only the first 50 validation issues are returned. Validation paths and messages are bounded.

Example response

Synthetic error example. Use the investigation match-review, submit and approval endpoints before recording a conclusion.

{
  "error": {
    "code": "investigation_review_required",
    "message": "Use the investigation workspace to review and approve every current match.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

case exists

Synthetic error example. Open the existing case and append your review there.

{
  "error": {
    "code": "case_exists",
    "message": "A review case already exists for this screening. Open that case to append a decision.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

410result_expired — Run a new screening and review its retained evidence. Expired evidence is not reconstructed.

Response headers

X-Request-Id

string

Server-generated correlation identifier, also returned in error.requestId.

Format: uuid.

application/jsonView Error schema

Response fields

Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.

Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.

errorRequired

object

error fields and rules

error.codeRequired

string

Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.

error.messageRequired

string

Human-readable explanation. Do not parse this text to control application behavior.

error.requestIdRequired

string

Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.

Format: uuid.

error.detailsOptional

object[] or object or string or number or boolean or null

error.details fields and rules

Allowed alternatives

object[]
Maximum items: 50.
Each array item: object.
error.details[].pathRequired
string
Dot-separated invalid field path, including array indexes.
Maximum length: 160.
error.details[].messageRequired
string
Validation problem for this field.
Maximum length: 300.
object
Additional keys are allowed; their values are not a fixed contract.
string or number or boolean or null
May be null.

error.detailsTruncatedOptional

boolean

True when only the first 50 validation issues are returned. Validation paths and messages are bounded.

Example response

Synthetic error example. Run a new screening and review its retained evidence. Expired evidence is not reconstructed.

{
  "error": {
    "code": "result_expired",
    "message": "The evidence has expired. Run a new screening before reviewing it.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

413response_too_large — Reduce the requested page size or use the documented segmented case archive. No evidence is silently truncated. invalid_request — Reduce the JSON request size to the documented limit.

Response headers

X-Request-Id

string

Server-generated correlation identifier, also returned in error.requestId.

Format: uuid.

application/jsonView Error schema

Response fields

Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.

Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.

errorRequired

object

error fields and rules

error.codeRequired

string

Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.

error.messageRequired

string

Human-readable explanation. Do not parse this text to control application behavior.

error.requestIdRequired

string

Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.

Format: uuid.

error.detailsOptional

object[] or object or string or number or boolean or null

error.details fields and rules

Allowed alternatives

object[]
Maximum items: 50.
Each array item: object.
error.details[].pathRequired
string
Dot-separated invalid field path, including array indexes.
Maximum length: 160.
error.details[].messageRequired
string
Validation problem for this field.
Maximum length: 300.
object
Additional keys are allowed; their values are not a fixed contract.
string or number or boolean or null
May be null.

error.detailsTruncatedOptional

boolean

True when only the first 50 validation issues are returned. Validation paths and messages are bounded.

Example response

Synthetic error example. Reduce the requested page size or use the documented segmented case archive. No evidence is silently truncated.

{
  "error": {
    "code": "response_too_large",
    "message": "This response exceeds the size limit. Request a smaller page or a segmented export.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

invalid request

Synthetic error example. Reduce the JSON request size to the documented limit.

{
  "error": {
    "code": "invalid_request",
    "message": "REQUEST_TOO_LARGE",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

415invalid_request — Use Content-Type: application/json and an uncompressed UTF-8 body.

Response headers

X-Request-Id

string

Server-generated correlation identifier, also returned in error.requestId.

Format: uuid.

application/jsonView Error schema

Response fields

Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.

Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.

errorRequired

object

error fields and rules

error.codeRequired

string

Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.

error.messageRequired

string

Human-readable explanation. Do not parse this text to control application behavior.

error.requestIdRequired

string

Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.

Format: uuid.

error.detailsOptional

object[] or object or string or number or boolean or null

error.details fields and rules

Allowed alternatives

object[]
Maximum items: 50.
Each array item: object.
error.details[].pathRequired
string
Dot-separated invalid field path, including array indexes.
Maximum length: 160.
error.details[].messageRequired
string
Validation problem for this field.
Maximum length: 300.
object
Additional keys are allowed; their values are not a fixed contract.
string or number or boolean or null
May be null.

error.detailsTruncatedOptional

boolean

True when only the first 50 validation issues are returned. Validation paths and messages are bounded.

Example response

Synthetic error example. Use Content-Type: application/json and an uncompressed UTF-8 body.

{
  "error": {
    "code": "invalid_request",
    "message": "Send application/json with UTF-8 encoding.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

422retained_screening_required — Create a standard-retention screening before opening a case.

Response headers

X-Request-Id

string

Server-generated correlation identifier, also returned in error.requestId.

Format: uuid.

application/jsonView Error schema

Response fields

Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.

Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.

errorRequired

object

error fields and rules

error.codeRequired

string

Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.

error.messageRequired

string

Human-readable explanation. Do not parse this text to control application behavior.

error.requestIdRequired

string

Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.

Format: uuid.

error.detailsOptional

object[] or object or string or number or boolean or null

error.details fields and rules

Allowed alternatives

object[]
Maximum items: 50.
Each array item: object.
error.details[].pathRequired
string
Dot-separated invalid field path, including array indexes.
Maximum length: 160.
error.details[].messageRequired
string
Validation problem for this field.
Maximum length: 300.
object
Additional keys are allowed; their values are not a fixed contract.
string or number or boolean or null
May be null.

error.detailsTruncatedOptional

boolean

True when only the first 50 validation issues are returned. Validation paths and messages are bounded.

Example response

Synthetic error example. Create a standard-retention screening before opening a case.

{
  "error": {
    "code": "retained_screening_required",
    "message": "Case review requires a standard-retention screening.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

429rate_limited — Wait for the request window to reset and retry with backoff.

Response headers

X-Request-Id

string

Server-generated correlation identifier, also returned in error.requestId.

Format: uuid.

Retry-After

string

When present, a delay in seconds or an HTTP-date before which the client should not retry. Service-unavailable responses default to a one-second delay unless another safe value is supplied. A usage allowance error may require quota recovery instead of retrying.

application/jsonView Error schema

Response fields

Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.

Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.

errorRequired

object

error fields and rules

error.codeRequired

string

Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.

error.messageRequired

string

Human-readable explanation. Do not parse this text to control application behavior.

error.requestIdRequired

string

Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.

Format: uuid.

error.detailsOptional

object[] or object or string or number or boolean or null

error.details fields and rules

Allowed alternatives

object[]
Maximum items: 50.
Each array item: object.
error.details[].pathRequired
string
Dot-separated invalid field path, including array indexes.
Maximum length: 160.
error.details[].messageRequired
string
Validation problem for this field.
Maximum length: 300.
object
Additional keys are allowed; their values are not a fixed contract.
string or number or boolean or null
May be null.

error.detailsTruncatedOptional

boolean

True when only the first 50 validation issues are returned. Validation paths and messages are bounded.

Example response

Synthetic error example. Wait for the request window to reset and retry with backoff.

{
  "error": {
    "code": "rate_limited",
    "message": "The per-minute request limit has been reached.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

500internal_error — Retry with backoff. For writes reuse the same idempotency key and identical input; include requestId when contacting support.

Response headers

X-Request-Id

string

Server-generated correlation identifier, also returned in error.requestId.

Format: uuid.

application/jsonView Error schema

Response fields

Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.

Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.

errorRequired

object

error fields and rules

error.codeRequired

string

Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.

error.messageRequired

string

Human-readable explanation. Do not parse this text to control application behavior.

error.requestIdRequired

string

Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.

Format: uuid.

error.detailsOptional

object[] or object or string or number or boolean or null

error.details fields and rules

Allowed alternatives

object[]
Maximum items: 50.
Each array item: object.
error.details[].pathRequired
string
Dot-separated invalid field path, including array indexes.
Maximum length: 160.
error.details[].messageRequired
string
Validation problem for this field.
Maximum length: 300.
object
Additional keys are allowed; their values are not a fixed contract.
string or number or boolean or null
May be null.

error.detailsTruncatedOptional

boolean

True when only the first 50 validation issues are returned. Validation paths and messages are bounded.

Example response

Synthetic error example. Retry with backoff. For writes reuse the same idempotency key and identical input; include requestId when contacting support.

{
  "error": {
    "code": "internal_error",
    "message": "The request could not be completed.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

503temporarily_unavailable — Honor Retry-After when present and retry with bounded backoff. Follow this endpoint’s retry contract; preserve the same key and input for idempotent writes. Contact support with requestId if the failure persists.

Response headers

X-Request-Id

string

Server-generated correlation identifier, also returned in error.requestId.

Format: uuid.

Retry-After

string

application/jsonView Error schema

Response fields

Required means present in the containing object. Optional fields may be omitted; null is allowed only where stated. Array item fields apply to every item.

Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.

errorRequired

object

error fields and rules

error.codeRequired

string

Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.

error.messageRequired

string

Human-readable explanation. Do not parse this text to control application behavior.

error.requestIdRequired

string

Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.

Format: uuid.

error.detailsOptional

object[] or object or string or number or boolean or null

error.details fields and rules

Allowed alternatives

object[]
Maximum items: 50.
Each array item: object.
error.details[].pathRequired
string
Dot-separated invalid field path, including array indexes.
Maximum length: 160.
error.details[].messageRequired
string
Validation problem for this field.
Maximum length: 300.
object
Additional keys are allowed; their values are not a fixed contract.
string or number or boolean or null
May be null.

error.detailsTruncatedOptional

boolean

True when only the first 50 validation issues are returned. Validation paths and messages are bounded.

Example response

Synthetic error example. Honor Retry-After when present and retry with bounded backoff. Follow this endpoint’s retry contract; preserve the same key and input for idempotent writes. Contact support with requestId if the failure persists.

{
  "error": {
    "code": "temporarily_unavailable",
    "message": "The service is temporarily unavailable. Retry shortly.",
    "requestId": "01234567-89ab-4cde-8f01-23456789abcd"
  }
}

Back to request parameters