> ## Documentation Index
> Fetch the complete documentation index at: https://docs.amlok.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Handle stable error codes, correlation IDs, validation failures, and recoverable outages.

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

```json theme={null}
{
  "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](https://docs.amlok.io/api-reference/processing-lifecycle.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.