Errors

Errors use a stable code and a safe explanation. Do not branch on human-readable message text.

{
  "error": {
    "code": "invalid_search_scope",
    "message": "At least one supported jurisdiction is required.",
    "field": "jurisdictions",
    "retryable": false,
    "request_id": "req_example"
  },
  "meta": {
    "request_id": "req_example",
    "schema_version": "1.4.2",
    "generated_at": "2026-10-23T14:00:00Z",
    "data_status": "complete"
  }
}

The example has HTTP 422. meta.data_status: complete describes the error response, not successful completion of the requested workflow.

Error catalog

Code	HTTP	Retryable	Client action
`idempotency_result_expired`	409	No re-execution	Look up the durable request receipt.
`event_history_expired`	410	No	Reconcile current state through checkpoints and changes.
`validation_error`	400	No	Correct the invalid field or projection.
`cursor_expired`	410	No	Create a new synchronization checkpoint and rebuild the snapshot.
`workload_limit_exceeded`	422	No, until scope is agreed	Inspect the workload report and agree expanded scope before processing.
`invalid_request`	400	No	Correct request structure.
`unauthenticated`	401	No	Use a valid credential for the intended environment.
`forbidden`	403	No	Resolve authorization; do not retry with broader subject IDs.
`not_found`	404	No	Check resource ID and environment.
`idempotency_conflict`	409	No	Use original input or a new key for a genuinely new action.
`version_conflict`	412	No	Re-read and reconcile the change before submitting.
`invalid_search_scope`	422	No	Select supported explicit jurisdictions and identifiers.
`invalid_money`	422	No	Send exact decimal and valid currency context.
`insufficient_evidence`	422	No	Supply evidence; individual metric outputs may instead return unavailable.
`unsupported_parameter`	400	No	Use a supported query; do not substitute current data as historical.
`rate_limited`	429	Yes	Respect Retry-After and bounded backoff.
`source_error`	502	Conditional	Inspect job-level details; retry only if the failure is transient.
`source_unavailable`	503	Yes	Retry with backoff or retrieve explicit partial results.
`internal_error`	500	Conditional	Use request_id for support; keep idempotency key for safe retry.
`insufficient_credits`	402	No, until funded	Fund the workspace in the portal, then retry the rejected workflow. Unprocessed work is not charged.
`invalid_state`	409	No, until state permits	Operational commands stop immediately on cancellation. Read-only reporting remains available until deletion; report downloads require a ready export.

Retry decisions

Honor error.retryable and Retry-After when provided. A source error or internal error can require investigation; its HTTP class alone does not establish that repeating a command is safe. Preserve the idempotency key for the same POST action. Do not retry malformed input, invalid credentials, missing permissions, or stale resource versions without resolving the cause. Do not broaden subject IDs or permissions in response to an authorization error.

Insufficient credits

A billable workflow returns 402 insufficient_credits when available credits cannot cover its cost. CAD 200.00 is an automatic top-up trigger, not a processing floor. Requests may continue below it while funded. Pending payments are excluded from available credits. The rejection occurs before work is accepted, without a usage debit. After credits are available, retry the same intended request with the same idempotency key; a pre-execution insufficient-credit rejection does not reserve the key as an accepted operation. Read-only reports and baseline retrieval do not require a new usage charge. Signal reassessment is included in Signal, not billed as another Insights underwriting.

Partial results versus request errors

A valid request can return usable partial data with meta.data_status: partial. Job-level errors and resource missing_fields explain the missing scope. Do not treat a 200 as evidence that every provider succeeded, or an unavailable metric as zero.

Diagnostics

Record the AMLOK request_id, operation, timestamp, environment, HTTP status, error code, and relevant resource/job IDs in your restricted operational logs. Redact keys, signing secrets, signed links, raw identity evidence, and full response bodies. Provide sanitized request IDs through your agreed support channel. Your agreement defines support channels and response commitments. For an accepted job that later runs short of credits, inspect waiting_for_credits rather than submitting a duplicate run. See processing lifecycle.

Get started

Endpoints

Essentials

Error catalog

Retry decisions

Insufficient credits

Partial results versus request errors

Diagnostics

​Error catalog

​Retry decisions

​Insufficient credits

​Partial results versus request errors

​Diagnostics

Error catalog

Retry decisions

Insufficient credits

Partial results versus request errors

Diagnostics