API REFERENCE · Screening and evidence

Retrieve one retained screening

Complete request parameters, body fields, response formats, examples, and errors for GET /results/{id}.

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

GET/results/{id}Retrieve one retained screening

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

Required API key scope: results:read.

Request parameters

Path parameters: id
Query parameters: None.
Headers: Authorization (required)
JSON body fields: None.

This operation has no request body.

Headers, path and query parameters

idpathRequired

string

Opaque resource identifier owned by the authenticated organization.

Format: uuid.

Request body

This operation has no request body.

Responses

200Successful 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

object

GET /results/{id} adds the retained subject and reference to the original result. Both keys are always present here and are null for minimal retention. POST /screenings and GET /results list items return ScreeningResult without these additions.

View RetainedScreeningResult schema

data fields and rules

data.idRequired

string

Screening UUID; use it to retrieve retained result/evidence and locate linked review cases.

Format: uuid.

data.environmentRequired

enum

Environment owned by the API key. Sandbox evidence is synthetic.

Values: "sandbox", "production".

data.statusRequired

enum

potential_match requires review of candidates; no_match means no returned candidates within the selected coverage and matching rules. Neither is a business approval or legal clearance.

Values: "potential_match", "no_match".

data.createdAtRequired

string

Screening creation timestamp in ISO 8601 UTC.

Format: date-time.

data.matchesRequired

object[]

Candidate records with field evidence and conflicts. Always an array; empty for no_match. No silent truncation is performed.

data.matches item fields

Each array item: object.

data.matches[].recordRequired

objectView SourceRecord schema

data.matches[].record fields and rules

See all SourceRecord fields for the complete structure, required properties and constraints.

data.matches[].scoreRequired

number

Similarity measure, not probability of wrongdoing.

Minimum: 0. Maximum: 100.

data.matches[].evidenceRequired

object[]

data.matches[].evidence item fields

Each array item: object.

data.matches[].evidence[].fieldRequired: string
data.matches[].evidence[].queryValueRequired: string
data.matches[].evidence[].sourceValueRequired: string
data.matches[].evidence[].methodRequired: string
data.matches[].evidence[].contributionRequired: number
data.matches[].evidence[].explanationRequired: string

data.matches[].conflictsRequired

string[]

data.matches[].conflicts item fields

Each array item: string.

data.coverageRequired

Coverage[]

Exact source versions used, including freshness and retained publisher notices. Always present, including no_match.

data.coverage item fields

Each array item: Coverage.

See all Coverage fields for the complete structure, required properties and constraints.

data.versionsRequired

object

Dataset, matching engine and policy versions used for this result. package is included only for package-based coverage.

data.versions fields and rules

data.versions.datasetRequired: string
data.versions.matchingEngineRequired: string
data.versions.policyRequired: string
data.versions.packageOptional: string

data.disclaimerRequired

string

Interpretation limits supplied with this result; preserve them when presenting or exporting evidence.

data.policySnapshotOptional

object

Immutable organization policy applied at screening time, when one was selected. Omitted when no organization policy applied.

View ScreeningPolicySnapshot schema

data.policySnapshot fields and rules

data.policySnapshot.nameRequired

string

Minimum length: 2. Maximum length: 120.

data.policySnapshot.purposeRequired

string

Minimum length: 3. Maximum length: 1000.

data.policySnapshot.jurisdictionsRequired

string[]

Minimum items: 1. Maximum items: 30.

data.policySnapshot.jurisdictions item fields

Each array item: string.

Minimum length: 2. Maximum length: 100.

data.policySnapshot.requiredSourcesRequired

object

Allowed keys: "person", "organization", "vessel", "aircraft", "other". Default: {}.

data.policySnapshot.requiredSources fields and rules

Each additional key uses the following value structure.

Maximum items: 512.

Each array item: string.

Minimum length: 1. Maximum length: 80.

data.policySnapshot.optionalSourcesRequired

object

Allowed keys: "person", "organization", "vessel", "aircraft", "other". Default: {}.

data.policySnapshot.optionalSources fields and rules

Each additional key uses the following value structure.

Maximum items: 512.

Each array item: string.

Minimum length: 1. Maximum length: 80.

data.policySnapshot.exclusionsRequired

string[]

Maximum items: 30. Default: [].

data.policySnapshot.exclusions item fields

Each array item: string.

Minimum length: 3. Maximum length: 500.

data.policySnapshot.externalChecksRequired

string[]

Maximum items: 20. Default: [].

data.policySnapshot.externalChecks item fields

Each array item: string.

Minimum length: 3. Maximum length: 200.

data.policySnapshot.externalCheckGuidanceOptional

object[]

Maximum items: 20.

data.policySnapshot.externalCheckGuidance item fields

Each array item: object.

data.policySnapshot.externalCheckGuidance[].labelRequired: string
Minimum length: 3. Maximum length: 200.
data.policySnapshot.externalCheckGuidance[].instructionsRequired: string
Minimum length: 3. Maximum length: 2000.
data.policySnapshot.externalCheckGuidance[].evidenceExampleOptional: string
Minimum length: 3. Maximum length: 1000.

Additional fields are not accepted.

data.policySnapshot.reviewRequired

object

Default: {}.

data.policySnapshot.review fields and rules

data.policySnapshot.review.requireSecondReviewOptional: boolean
Default: false.
data.policySnapshot.review.secondReviewForOptional: string[]
Maximum items: 4. Default: [].; data.policySnapshot.review.secondReviewFor item fields
Each array item: string.
Values: "same_identity", "allow", "restrict", "escalate".
data.policySnapshot.review.approverRolesOptional: string[]
Minimum items: 1. Maximum items: 3. Default: ["owner","admin","analyst"].; data.policySnapshot.review.approverRoles item fields
Each array item: string.
Values: "owner", "admin", "analyst".

Additional fields are not accepted.

data.policySnapshot.monitoringIntervalHoursRequired

6 or 24 or 168

Default: 24.

data.policySnapshot.monitoringIntervalHours fields and rules

Allowed alternatives

6
Must equal 6.
24
Must equal 24.
168
Must equal 168.

data.policySnapshot.retentionTriggerRequired

string

Values: "review_completed", "relationship_ended", "business_event". Default: "review_completed".

data.policySnapshot.idRequired

string

Format: uuid.

data.policySnapshot.versionRequired

integer

Minimum: 0.

data.policySnapshot.environmentRequired

string

Values: "sandbox", "production".

data.policySnapshot.createdAtRequired

string

Format: date-time.

Additional fields are not accepted.

data.subjectRequired

Subject or null

May be null.

data.subject fields and rules

Allowed alternatives

Subject
See all Subject fields for the complete structure, required properties and constraints.
null
May be null.

data.referenceRequired

string or null

May be null.

data.reference fields and rules

Allowed alternatives

string
null
May be null.

Example response

Recorded from the real application handler against an isolated synthetic database. IDs, times and nonfunctional temporary secrets are normalized. No customer data or live provider request.

{
  "data": {
    "id": "00000000-0000-4000-8000-000000000001",
    "status": "potential_match",
    "matches": [
      {
        "score": 96,
        "record": {
          "id": "sandbox:person-001",
          "list": "Synthetic demonstration records",
          "names": [
            {
              "kind": "primary",
              "value": "Alex Morgan"
            },
            {
              "kind": "alias",
              "value": "Алекс Морган"
            }
          ],
          "sourceId": "sandbox-synthetic",
          "addresses": [],
          "authority": "SanctionsKit synthetic examples",
          "sourceUrl": "https://sanctionskit.com/demo",
          "birthDates": [
            {
              "value": "1984",
              "original": "1984",
              "precision": "year"
            }
          ],
          "entityType": "person",
          "extensions": {
            "synthetic": true
          },
          "identifiers": [
            {
              "type": "passport",
              "value": "DEMO-001",
              "issuer": "Fictional authority"
            }
          ],
          "designations": [
            {
              "wording": "Invented example, not a government designation.",
              "category": "other",
              "programs": [
                "Synthetic demonstration only"
              ],
              "legalReferences": []
            }
          ],
          "nationalities": []
        },
        "evidence": [
          {
            "field": "name",
            "method": "normalized_name_exact",
            "queryValue": "Alex Morgan",
            "explanation": "Name similarity is a review signal, not a probability or finding of wrongdoing.",
            "sourceValue": "Alex Morgan",
            "contribution": 96
          }
        ],
        "conflicts": []
      }
    ],
    "coverage": [
      {
        "fresh": true,
        "version": "1",
        "sourceId": "sandbox-synthetic",
        "retrievedAt": "2026-09-17T12:00:00.000Z"
      }
    ],
    "versions": {
      "policy": "review-1.1.0",
      "dataset": "sandbox-synthetic-v1",
      "package": "sandbox@1",
      "matchingEngine": "deterministic-1.1.1"
    },
    "createdAt": "2026-09-17T12:00:00.000Z",
    "disclaimer": "Potential matches support analyst review. No match means no match in the selected sources and dataset, not legal clearance. Scores are similarity measures, not probabilities of wrongdoing.",
    "environment": "sandbox",
    "policySnapshot": {
      "id": "00000000-0000-4000-8000-000000000002",
      "name": "Synthetic onboarding policy",
      "review": {
        "approverRoles": [
          "owner",
          "admin",
          "analyst"
        ],
        "secondReviewFor": [],
        "requireSecondReview": false
      },
      "purpose": "Document vendor onboarding checks",
      "version": 1,
      "createdAt": "2026-09-17T12:00:00.000Z",
      "exclusions": [],
      "environment": "sandbox",
      "jurisdictions": [
        "Example jurisdiction"
      ],
      "externalChecks": [
        "Ownership review"
      ],
      "optionalSources": {},
      "requiredSources": {},
      "retentionTrigger": "business_event",
      "monitoringIntervalHours": 24
    },
    "subject": {
      "name": "Alex Morgan",
      "entityType": "person",
      "identifiers": []
    },
    "reference": null
  }
}

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

Recorded from the real application handler against an isolated synthetic database. IDs, times and nonfunctional temporary secrets are normalized. No customer data or live provider request.

{
  "error": {
    "code": "not_found",
    "message": "Screening not found.",
    "requestId": "00000000-0000-4000-8000-000000000001"
  }
}

not found

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"
  }
}

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

Recorded from the real application handler against an isolated synthetic database. IDs, times and nonfunctional temporary secrets are normalized. No customer data or live provider request.

{
  "error": {
    "code": "result_expired",
    "message": "This screening evidence has expired under your retention policy.",
    "requestId": "00000000-0000-4000-8000-000000000001"
  }
}

result expired

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.

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"
  }
}

422result_too_large — Use more precise screening input. Large results are rejected rather than silently truncated.

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 more precise screening input. Large results are rejected rather than silently truncated.

{
  "error": {
    "code": "result_too_large",
    "message": "A retained result exceeds the response size limit. No matches were truncated or skipped.",
    "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