{
  "schemaVersion": "1.0",
  "title": "Troubleshoot Cal.diy",
  "description": "Use this runbook to trace a Cal.diy failure to the signed host, pinned route, credential, provider request, durable mutation, or webhook boundary. The result should be one explicit decision: correct, wait, retry a read within policy, reconc",
  "canonical": "https://getaip.org/docs/connectors/cal-diy/troubleshooting",
  "route": "/docs/connectors/cal-diy/troubleshooting",
  "source": "docs/connectors/cal-diy/troubleshooting/README.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Connectors",
  "documentType": "Connector",
  "language": "en",
  "downloads": {
    "md": "/docs/download/connectors/cal-diy/troubleshooting.md",
    "txt": "/docs/download/connectors/cal-diy/troubleshooting.txt",
    "json": "/docs/download/connectors/cal-diy/troubleshooting.json",
    "pdf": "/docs/download/connectors/cal-diy/troubleshooting.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Troubleshoot Cal.diy\ndescription: >-\n  Classify Cal.diy authentication, routing, provider, mutation, and webhook\n  failures and choose a safe next action\nkind: runbook\naudience: operator\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\nconnector: cal-diy\n---\n\n# Troubleshoot Cal.diy\n\nUse this runbook to trace a Cal.diy failure to the signed host, pinned route,\ncredential, provider request, durable mutation, or webhook boundary. The result\nshould be one explicit decision: correct, wait, retry a read within policy,\nreconcile, or escalate.\n\nPause new mutations whenever provider outcome is uncertain. Preserve the\noriginal action ID, idempotency key reference, route assignment, provider\noperation ID, provider request ID, and durable state before changing the\ndeployment.\n\n## Trust the right error shape\n\nDetermine where the failure appeared before interpreting its fields:\n\n| Surface | Evidence shape | Trust check |\n|---|---|---|\n| Connector-host AIP route | Signed error envelope containing `ProtocolError` | Verify host signature, sender, recipient, and request correlation |\n| Action lifecycle | `ActionResult` with `status: failed` and an error | Read the durable action even when HTTP succeeded |\n| Cal.diy webhook ingress | Compact `{ \"error\": { \"code\": \"...\" } }` | Use authenticated TLS and host evidence; this is not a signed AIP envelope |\n| Process startup | Error text and non-zero exit | Compare exact configuration and file ownership; no protocol code exists yet |\n\nAutomate on `code`, category, `retryable`, `uncertain_outcome`, and durable\nstate. Do not match message text or trust an unsigned pre-envelope response as\nauthenticated action state.\n\n## Choose the first check\n\n| Symptom | First check | Safe first action |\n|---|---|---|\n| Capability is absent | Authenticated tenant catalog and enabled binding | Correct discovery or admission; do not call a host directly |\n| Host returns `401` | `connector_host.authentication` versus `connector.cal_diy.authentication` | Repair the identified trust layer without broadening authority |\n| Host returns `403` | Signed route, credential-revision, approval, or provider code | Re-resolve the exact route or policy; do not bypass it |\n| `/health` works and `/ready` fails | `draining`, `lease_valid`, runtime, and connector fields | Follow the failing readiness boundary |\n| Read receives `429`, `5xx`, or transport failure | Capability retry support, retry hint, and budget | Retry only the same read through normal policy |\n| Mutation receives any ambiguous response | `uncertain_outcome` and provider operation | Reconcile before another mutation or compensation |\n| Same idempotency key is rejected | In-flight, collision, completed, or uncertain ledger state | Wait, reuse, correct, or reconcile as the state requires |\n| Booking plan says slot unavailable | Requested start and fresh slot evidence | Choose another slot and create a new plan |\n| Webhook receives `400`, `401`, or `503` | Compact webhook code and retained raw request evidence | Correct delivery or retry the exact accepted-safe delivery |\n\n## Diagnose authentication in order\n\nSeveral layers can return an authentication-looking error. Start at the first\nfailed boundary:\n\n1. `connector_host.authentication` means the request did not match the pinned\n   gateway principal, DID, signature, or trust domain. Correct the signed\n   gateway path.\n2. `connector_host.route_mismatch` means the signed assignment does not match\n   this type, version, instance, replica, endpoint, manifest, tenant, binding,\n   or fence. Discard it and resolve a current route.\n3. `connector_host.credential_revision_denied` or\n   `connector_host.credential_revision_unavailable` means the pinned revision\n   is denied or cannot be read. Restore the reviewed policy; do not select a\n   different credential silently.\n4. `connector.cal_diy.invalid_credential` means local credential material is\n   empty or structurally invalid before a useful provider exchange.\n5. `connector.cal_diy.authentication` means Cal.diy returned HTTP `401` or\n   `403`. Verify the intended account, credential mode, scope, expiry, and\n   provider-side status.\n\nThe standalone `aip-host-cal-diy` pins one account and one deployment\ncredential. The optional library credential-routing mode adds\n`connector.cal_diy.credential_resolution`. In that mode, inspect the verified\nactor, tenant membership, tenant-to-account binding, credential issuer, tenant,\noperation scope, expiry, resolved material, and account match in that order.\nDo not look for library routing configuration in a standalone host.\n\nAfter any credential repair, require `/ready` and route a non-mutating\n`cap:cal_diy:profile.get` through `aipd`. A successful direct provider request\ndoes not prove the AIP tenant and route boundary.\n\n## Separate discovery from account routing\n\nAn absent capability and a wrong Cal.diy account are different failures:\n\n| Observation | Owner | Decision |\n|---|---|---|\n| Tenant catalog omits the capability | Registry version, implementation support, or binding | Correct signed admission or use a published capability |\n| Catalog contains it but no ready replica exists | Lease, health, topology, or capacity | Restore an admitted replica; keep the action at the gateway |\n| Host reports route mismatch | Pinned assignment versus host identity | Re-resolve; never edit the signed route |\n| Provider result belongs to an unexpected account | Instance, external account, or credential ownership | Stop traffic and treat it as an isolation incident |\n| Optional library route has no account binding | Verified tenant mapping | Add the reviewed mapping; do not fall back to a default account |\n\nThe standalone host does not dynamically choose among accounts. Changing its\naccount ID or provider credential is a deployment change, not request recovery.\n\n## Interpret provider responses by operation type\n\nThe client retains a redacted provider code, HTTP status, request ID, and\nparsed `Retry-After`. It does not expose the raw provider error body.\n\n| Provider observation | Connector code | Read decision | Mutation decision |\n|---|---|---|---|\n| HTTP `401` or `403` | `connector.cal_diy.authentication` | Correct credential or scope | Definitive rejection; correct authority before a new reviewed attempt |\n| HTTP `409` or `412` | `connector.cal_diy.state_conflict` | Refresh resource state | Definitive rejection; re-plan from current state |\n| HTTP `429` | `connector.cal_diy.rate_limited` | Honor bounded policy and `Retry-After` | Ledger records not committed; do not auto-retry because mutation retry support is false |\n| HTTP `500`–`599` | `connector.cal_diy.remote_temporary` | Bounded read retry may be eligible | Outcome is uncertain; reconcile |\n| Transport failure | `connector.cal_diy.transport` | Bounded read retry may be eligible | Outcome is uncertain; reconcile |\n| Response exceeds configured bound | `connector.cal_diy.response_too_large` | Review the operation and safe limit | Outcome is uncertain after dispatch; reconcile |\n| Successful response is invalid JSON or schema | `connector.cal_diy.invalid_request` or `connector.cal_diy.invalid_provider_output` | Stop and inspect upstream compatibility | Outcome is uncertain for a mutation; reconcile |\n| Other HTTP `400`–`499`, except `408` | `connector.cal_diy.remote_rejected` | Correct request or state | Definitive rejection; use a new plan when corrected |\n| HTTP `408` or a `2xx` body with `status: error` | `connector.cal_diy.remote_rejected` | Inspect provider evidence before retry | Source treats the dispatch as uncertain; reconcile |\n\nFor a mutation, `retryable: true` on rate limiting does not override the\nconnector's published implementation support, which enables automatic retry\nonly for reads. A definitive rejection can establish `not_committed`, but a\nnew attempt still requires the same operation, idempotency key, and input plus\nthe owning action or transaction policy.\n\n## Look up Cal.diy connector codes\n\nThe following groups cover every explicit `connector.cal_diy.*` code at the\npinned revision. The generic `connector.cal_diy` fallback represents an\nunexpected non-typed connector error.\n\n### Input, policy, and planning\n\n| Code | Category and retry | Decision |\n|---|---|---|\n| `connector.cal_diy.invalid_action` | Permanent, false | Correct unsupported capability, schema, path field, or connector-owned webhook rule |\n| `connector.cal_diy.invalid_request` | Permanent, false | Correct local URL or input construction, or investigate invalid provider JSON |\n| `connector.cal_diy.policy` | Policy, false | Supply required idempotency or an approved webhook secret reference |\n| `connector.cal_diy.transaction_required` | Policy, false | Use plan and commit for booking create, reschedule, or cancel |\n| `connector.cal_diy.slot_unavailable` | Policy, false | Refresh slots and plan another start time |\n| `connector.cal_diy.idempotency_collision` | Policy, false | Stop; the key owns a different operation or input |\n\n### Credential and provider\n\n| Code | Category and retry | Decision |\n|---|---|---|\n| `connector.cal_diy.credential_resolution` | Auth, false | Repair the optional verified tenant and credential-handle chain |\n| `connector.cal_diy.invalid_credential` | Auth, false | Replace invalid local material through credential rotation |\n| `connector.cal_diy.authentication` | Auth, false | Correct provider credential, scope, account, or provider access |\n| `connector.cal_diy.state_conflict` | Policy, false | Refresh provider state and re-plan |\n| `connector.cal_diy.rate_limited` | Temporary, conditional | Reads may honor `Retry-After`; mutations require ledger-state review |\n| `connector.cal_diy.remote_temporary` | Temporary, conditional | Retry a read within policy; reconcile a mutation |\n| `connector.cal_diy.remote_rejected` | Permanent, false | Use status and mutation certainty to correct or reconcile |\n| `connector.cal_diy.transport` | Transport, conditional | Retry a read within policy; reconcile a mutation |\n| `connector.cal_diy.response_too_large` | Transport, false | Review the response contract and deployment limit |\n| `connector.cal_diy.invalid_provider_output` | Connector, false | Retain status and request ID; inspect upstream drift |\n| `connector.cal_diy.client` | Connector, false | Diagnose the wrapped client boundary and retain redacted evidence |\n\n### Durable mutation and reconciliation\n\n| Code | Category and retry | Decision |\n|---|---|---|\n| `connector.cal_diy.in_flight` | Temporary, true | Wait for the current owner; do not create another action |\n| `connector.cal_diy.outcome_unknown` | Temporary, false | Reconcile the returned provider operation ID |\n| `connector.cal_diy.cancelled` | Temporary, false | Check `uncertain_outcome`; cancellation after dispatch requires reconciliation |\n| `connector.cal_diy.state` | Temporary, false | Restore PostgreSQL and inspect the existing record |\n| `connector.cal_diy.pre_dispatch_state` | Temporary, false, 120-second hint | Dispatch did not begin, but claim cleanup failed; wait and reconcile before reuse |\n| `connector.cal_diy.post_dispatch_state` | Temporary, false, uncertain | Settlement failed after the dispatch boundary; use checkpoint and provider evidence |\n| `connector.cal_diy.reconciliation_not_found` | Permanent, false | Verify provider operation ID, account scope, retained database, and route |\n\n### Webhook and fallback\n\n| Code | Category and retry | Decision |\n|---|---|---|\n| `connector.cal_diy.webhook_auth` | Auth, false | Correct subscription, secret reference, and exact raw-body signature |\n| `connector.cal_diy.webhook_policy` | Policy, false | Correct version, timestamp, or replay condition |\n| `connector.cal_diy` | Connector, false | Retain the typed source and escalate an unexpected connector failure |\n\nCategory and retry describe the emitted error. The mutation ledger remains the\nauthority for replay safety.\n\n## Decide whether to retry\n\nApply this order. Stop at the first unmet condition:\n\n1. Verify the signed response or read the durable action result.\n2. Determine whether the operation is a read or mutation.\n3. For a mutation, read its provider operation and reconciliation state. If the\n   state is not terminal `not_committed`, do not retry.\n4. Require capability and implementation retry support. At this revision,\n   Cal.diy publishes retry implementation support only for reads.\n5. Require `retryable` not to be false and respect the action's attempt,\n   elapsed-time, and backoff budgets.\n6. Let the runtime retry the same read action according to policy; do not\n   bypass the gateway with a provider call.\n\n`connector.cal_diy.in_flight` means another attempt owns the key, not that a\nsecond call is needed. `connector.cal_diy.idempotency_collision` means the key\nwas reused with different input and must not be repaired by changing stored\nstate.\n\n## Resolve an unknown mutation outcome\n\nWhen `uncertain_outcome` is true or the code is\n`connector.cal_diy.outcome_unknown` or\n`connector.cal_diy.post_dispatch_state`:\n\n1. freeze new mutations for the affected resource;\n2. retain the original action, transaction, idempotency, provider operation,\n   request, and route identifiers;\n3. read the existing action and transaction state;\n4. invoke the normal reconciliation path with the exact provider operation ID;\n5. correlate Cal.diy audit or resource state and any embedded AIP booking\n   metadata;\n6. accept `committed` or `not_committed` only from durable trusted evidence;\n7. keep the result nonterminal when evidence remains ambiguous;\n8. compensate only after the committed effect is identified and the\n   capability contract permits compensation.\n\nA stale pre-dispatch `claimed` record can become `not_committed`. A stale\n`dispatching` record becomes `uncertain`. Waiting 120 seconds is therefore not\nby itself permission to replay a dispatched mutation.\n\n## Troubleshoot webhook ingress\n\nThe standalone route returns compact HTTP errors:\n\n| Code | HTTP | Decision |\n|---|---:|---|\n| `webhook.missing_header` | 400 | Preserve the request and restore both required headers |\n| `webhook.invalid_utf8` | 400 | Correct the sender or proxy; signature verification requires exact UTF-8 bytes |\n| `webhook.authentication_failed` | 401 | Check subscription mapping, secret, signature encoding, and raw-body preservation |\n| `webhook.invalid_delivery` | 400 | Check version, timestamp window, JSON payload, and replay evidence |\n| `webhook.storage_unavailable` | 503 | Restore replay, event-log, or outbox storage; retry the exact delivery |\n| `webhook.invalid_mapping` | 500 | Retain the delivery and escalate an impossible connector mapping |\n\nA successful response can report `durably_queued` rather than central\nacknowledgement. Recover central publication from the retained outbox; do not\nask Cal.diy to generate a new event. Follow\n[Webhook security and replay](../reference/webhook-security-and-replay.md) for\nthe exact HMAC, timestamp, duplicate, and delivery contract.\n\n## Resolve startup failures\n\nStartup failures precede the AIP error surface. Inspect the first process error\nand compare it with [Cal.diy configuration](../reference/configuration.md).\nCommon causes include:\n\n- an invalid base URL or account ID;\n- a mixed or incomplete authentication mode;\n- a secret file that is unreadable or exceeds its configured bound;\n- an invalid webhook secret mapping;\n- a missing central event endpoint for enabled ingress;\n- a database or manifest-discovery failure; or\n- a registry identity mismatch.\n\nCorrect one owning boundary at a time. Re-run readiness and the gateway-routed\nprofile read after every change; do not combine credential, account, artifact,\nand registry changes into one diagnostic restart.\n\n## Verify the resolution\n\nClose the incident only when:\n\n- the signed error or startup failure no longer occurs for the corrected path;\n- `/ready`, the lifecycle lease, and tenant discovery agree;\n- a gateway-routed profile read reaches the intended account;\n- the original mutation is terminal or remains explicitly paused as uncertain;\n- the exact accepted webhook event appears centrally when ingress was affected;\n- no credential, raw provider body, webhook secret, or personal data entered\n  logs or the incident record.\n\nEscalate with:\n\n- the source revision plus artifact and manifest digests;\n- the tenant-safe identity set and timestamps;\n- the signed error plus action and transaction state;\n- provider operation and request IDs;\n- remote status, retry hint, and uncertainty flag;\n- readiness fields and metric snapshots; and\n- webhook event IDs and redacted logs.\n\n## Related documentation\n\n- [Errors and retry decisions](../../../reference/errors.md)\n- [Cal.diy authentication and tenant\n  routing](../getting-started/authentication-and-tenant-routing.md)\n- [Cal.diy configuration](../reference/configuration.md)\n- [Recover the Cal.diy connector](../operations/health-observability-and-recovery.md)\n- [Cal.diy webhook security and replay](../reference/webhook-security-and-replay.md)\n",
    "text": "Troubleshoot Cal.diy\n\nUse this runbook to trace a Cal.diy failure to the signed host, pinned route,\ncredential, provider request, durable mutation, or webhook boundary. The result\nshould be one explicit decision: correct, wait, retry a read within policy,\nreconcile, or escalate.\n\nPause new mutations whenever provider outcome is uncertain. Preserve the\noriginal action ID, idempotency key reference, route assignment, provider\noperation ID, provider request ID, and durable state before changing the\ndeployment.\n\nTrust the right error shape\n\nDetermine where the failure appeared before interpreting its fields:\n\n| Surface | Evidence shape | Trust check |\n\n| Connector-host AIP route | Signed error envelope containing ProtocolError | Verify host signature, sender, recipient, and request correlation |\n| Action lifecycle | ActionResult with status: failed and an error | Read the durable action even when HTTP succeeded |\n| Cal.diy webhook ingress | Compact { \"error\": { \"code\": \"...\" } } | Use authenticated TLS and host evidence; this is not a signed AIP envelope |\n| Process startup | Error text and non-zero exit | Compare exact configuration and file ownership; no protocol code exists yet |\n\nAutomate on code, category, retryable, uncertainoutcome, and durable\nstate. Do not match message text or trust an unsigned pre-envelope response as\nauthenticated action state.\n\nChoose the first check\n\n| Symptom | First check | Safe first action |\n\n| Capability is absent | Authenticated tenant catalog and enabled binding | Correct discovery or admission; do not call a host directly |\n| Host returns 401 | connectorhost.authentication versus connector.caldiy.authentication | Repair the identified trust layer without broadening authority |\n| Host returns 403 | Signed route, credential-revision, approval, or provider code | Re-resolve the exact route or policy; do not bypass it |\n| /health works and /ready fails | draining, leasevalid, runtime, and connector fields | Follow the failing readiness boundary |\n| Read receives 429, 5xx, or transport failure | Capability retry support, retry hint, and budget | Retry only the same read through normal policy |\n| Mutation receives any ambiguous response | uncertainoutcome and provider operation | Reconcile before another mutation or compensation |\n| Same idempotency key is rejected | In-flight, collision, completed, or uncertain ledger state | Wait, reuse, correct, or reconcile as the state requires |\n| Booking plan says slot unavailable | Requested start and fresh slot evidence | Choose another slot and create a new plan |\n| Webhook receives 400, 401, or 503 | Compact webhook code and retained raw request evidence | Correct delivery or retry the exact accepted-safe delivery |\n\nDiagnose authentication in order\n\nSeveral layers can return an authentication-looking error. Start at the first\nfailed boundary:\n1. connectorhost.authentication means the request did not match the pinned\n   gateway principal, DID, signature, or trust domain. Correct the signed\n   gateway path.\n2. connectorhost.routemismatch means the signed assignment does not match\n   this type, version, instance, replica, endpoint, manifest, tenant, binding,\n   or fence. Discard it and resolve a current route.\n3. connectorhost.credentialrevisiondenied or\n   connectorhost.credentialrevisionunavailable means the pinned revision\n   is denied or cannot be read. Restore the reviewed policy; do not select a\n   different credential silently.\n4. connector.caldiy.invalidcredential means local credential material is\n   empty or structurally invalid before a useful provider exchange.\n5. connector.caldiy.authentication means Cal.diy returned HTTP 401 or\n   403. Verify the intended account, credential mode, scope, expiry, and\n   provider-side status.\n\nThe standalone aip-host-cal-diy pins one account and one deployment\ncredential. The optional library credential-routing mode adds\nconnector.caldiy.credentialresolution. In that mode, inspect the verified\nactor, tenant membership, tenant-to-account binding, credential issuer, tenant,\noperation scope, expiry, resolved material, and account match in that order.\nDo not look for library routing configuration in a standalone host.\n\nAfter any credential repair, require /ready and route a non-mutating\ncap:caldiy:profile.get through aipd. A successful direct provider request\ndoes not prove the AIP tenant and route boundary.\n\nSeparate discovery from account routing\n\nAn absent capability and a wrong Cal.diy account are different failures:\n\n| Observation | Owner | Decision |\n\n| Tenant catalog omits the capability | Registry version, implementation support, or binding | Correct signed admission or use a published capability |\n| Catalog contains it but no ready replica exists | Lease, health, topology, or capacity | Restore an admitted replica; keep the action at the gateway |\n| Host reports route mismatch | Pinned assignment versus host identity | Re-resolve; never edit the signed route |\n| Provider result belongs to an unexpected account | Instance, external account, or credential ownership | Stop traffic and treat it as an isolation incident |\n| Optional library route has no account binding | Verified tenant mapping | Add the reviewed mapping; do not fall back to a default account |\n\nThe standalone host does not dynamically choose among accounts. Changing its\naccount ID or provider credential is a deployment change, not request recovery.\n\nInterpret provider responses by operation type\n\nThe client retains a redacted provider code, HTTP status, request ID, and\nparsed Retry-After. It does not expose the raw provider error body.\n\n| Provider observation | Connector code | Read decision | Mutation decision |\n\n| HTTP 401 or 403 | connector.caldiy.authentication | Correct credential or scope | Definitive rejection; correct authority before a new reviewed attempt |\n| HTTP 409 or 412 | connector.caldiy.stateconflict | Refresh resource state | Definitive rejection; re-plan from current state |\n| HTTP 429 | connector.caldiy.ratelimited | Honor bounded policy and Retry-After | Ledger records not committed; do not auto-retry because mutation retry support is false |\n| HTTP 500–599 | connector.caldiy.remotetemporary | Bounded read retry may be eligible | Outcome is uncertain; reconcile |\n| Transport failure | connector.caldiy.transport | Bounded read retry may be eligible | Outcome is uncertain; reconcile |\n| Response exceeds configured bound | connector.caldiy.responsetoolarge | Review the operation and safe limit | Outcome is uncertain after dispatch; reconcile |\n| Successful response is invalid JSON or schema | connector.caldiy.invalidrequest or connector.caldiy.invalidprovideroutput | Stop and inspect upstream compatibility | Outcome is uncertain for a mutation; reconcile |\n| Other HTTP 400–499, except 408 | connector.caldiy.remoterejected | Correct request or state | Definitive rejection; use a new plan when corrected |\n| HTTP 408 or a 2xx body with status: error | connector.caldiy.remoterejected | Inspect provider evidence before retry | Source treats the dispatch as uncertain; reconcile |\n\nFor a mutation, retryable: true on rate limiting does not override the\nconnector's published implementation support, which enables automatic retry\nonly for reads. A definitive rejection can establish notcommitted, but a\nnew attempt still requires the same operation, idempotency key, and input plus\nthe owning action or transaction policy.\n\nLook up Cal.diy connector codes\n\nThe following groups cover every explicit connector.caldiy. code at the\npinned revision. The generic connector.caldiy fallback represents an\nunexpected non-typed connector error.\n\nInput, policy, and planning\n\n| Code | Category and retry | Decision |\n\n| connector.caldiy.invalidaction | Permanent, false | Correct unsupported capability, schema, path field, or connector-owned webhook rule |\n| connector.caldiy.invalidrequest | Permanent, false | Correct local URL or input construction, or investigate invalid provider JSON |\n| connector.caldiy.policy | Policy, false | Supply required idempotency or an approved webhook secret reference |\n| connector.caldiy.transactionrequired | Policy, false | Use plan and commit for booking create, reschedule, or cancel |\n| connector.caldiy.slotunavailable | Policy, false | Refresh slots and plan another start time |\n| connector.caldiy.idempotencycollision | Policy, false | Stop; the key owns a different operation or input |\n\nCredential and provider\n\n| Code | Category and retry | Decision |\n\n| connector.caldiy.credentialresolution | Auth, false | Repair the optional verified tenant and credential-handle chain |\n| connector.caldiy.invalidcredential | Auth, false | Replace invalid local material through credential rotation |\n| connector.caldiy.authentication | Auth, false | Correct provider credential, scope, account, or provider access |\n| connector.caldiy.stateconflict | Policy, false | Refresh provider state and re-plan |\n| connector.caldiy.ratelimited | Temporary, conditional | Reads may honor Retry-After; mutations require ledger-state review |\n| connector.caldiy.remotetemporary | Temporary, conditional | Retry a read within policy; reconcile a mutation |\n| connector.caldiy.remoterejected | Permanent, false | Use status and mutation certainty to correct or reconcile |\n| connector.caldiy.transport | Transport, conditional | Retry a read within policy; reconcile a mutation |\n| connector.caldiy.responsetoolarge | Transport, false | Review the response contract and deployment limit |\n| connector.caldiy.invalidprovideroutput | Connector, false | Retain status and request ID; inspect upstream drift |\n| connector.caldiy.client | Connector, false | Diagnose the wrapped client boundary and retain redacted evidence |\n\nDurable mutation and reconciliation\n\n| Code | Category and retry | Decision |\n\n| connector.caldiy.inflight | Temporary, true | Wait for the current owner; do not create another action |\n| connector.caldiy.outcomeunknown | Temporary, false | Reconcile the returned provider operation ID |\n| connector.caldiy.cancelled | Temporary, false | Check uncertainoutcome; cancellation after dispatch requires reconciliation |\n| connector.caldiy.state | Temporary, false | Restore PostgreSQL and inspect the existing record |\n| connector.caldiy.predispatchstate | Temporary, false, 120-second hint | Dispatch did not begin, but claim cleanup failed; wait and reconcile before reuse |\n| connector.caldiy.postdispatchstate | Temporary, false, uncertain | Settlement failed after the dispatch boundary; use checkpoint and provider evidence |\n| connector.caldiy.reconciliationnotfound | Permanent, false | Verify provider operation ID, account scope, retained database, and route |\n\nWebhook and fallback\n\n| Code | Category and retry | Decision |\n\n| connector.caldiy.webhookauth | Auth, false | Correct subscription, secret reference, and exact raw-body signature |\n| connector.caldiy.webhookpolicy | Policy, false | Correct version, timestamp, or replay condition |\n| connector.caldiy | Connector, false | Retain the typed source and escalate an unexpected connector failure |\n\nCategory and retry describe the emitted error. The mutation ledger remains the\nauthority for replay safety.\n\nDecide whether to retry\n\nApply this order. Stop at the first unmet condition:\n1. Verify the signed response or read the durable action result.\n2. Determine whether the operation is a read or mutation.\n3. For a mutation, read its provider operation and reconciliation state. If the\n   state is not terminal notcommitted, do not retry.\n4. Require capability and implementation retry support. At this revision,\n   Cal.diy publishes retry implementation support only for reads.\n5. Require retryable not to be false and respect the action's attempt,\n   elapsed-time, and backoff budgets.\n6. Let the runtime retry the same read action according to policy; do not\n   bypass the gateway with a provider call.\n\nconnector.caldiy.inflight means another attempt owns the key, not that a\nsecond call is needed. connector.caldiy.idempotencycollision means the key\nwas reused with different input and must not be repaired by changing stored\nstate.\n\nResolve an unknown mutation outcome\n\nWhen uncertainoutcome is true or the code is\nconnector.caldiy.outcomeunknown or\nconnector.caldiy.postdispatchstate:\n1. freeze new mutations for the affected resource;\n2. retain the original action, transaction, idempotency, provider operation,\n   request, and route identifiers;\n3. read the existing action and transaction state;\n4. invoke the normal reconciliation path with the exact provider operation ID;\n5. correlate Cal.diy audit or resource state and any embedded AIP booking\n   metadata;\n6. accept committed or notcommitted only from durable trusted evidence;\n7. keep the result nonterminal when evidence remains ambiguous;\n8. compensate only after the committed effect is identified and the\n   capability contract permits compensation.\n\nA stale pre-dispatch claimed record can become notcommitted. A stale\ndispatching record becomes uncertain. Waiting 120 seconds is therefore not\nby itself permission to replay a dispatched mutation.\n\nTroubleshoot webhook ingress\n\nThe standalone route returns compact HTTP errors:\n\n| Code | HTTP | Decision |\n\n| webhook.missingheader | 400 | Preserve the request and restore both required headers |\n| webhook.invalidutf8 | 400 | Correct the sender or proxy; signature verification requires exact UTF-8 bytes |\n| webhook.authenticationfailed | 401 | Check subscription mapping, secret, signature encoding, and raw-body preservation |\n| webhook.invaliddelivery | 400 | Check version, timestamp window, JSON payload, and replay evidence |\n| webhook.storageunavailable | 503 | Restore replay, event-log, or outbox storage; retry the exact delivery |\n| webhook.invalidmapping | 500 | Retain the delivery and escalate an impossible connector mapping |\n\nA successful response can report durablyqueued rather than central\nacknowledgement. Recover central publication from the retained outbox; do not\nask Cal.diy to generate a new event. Follow\nWebhook security and replay (../reference/webhook-security-and-replay.md) for\nthe exact HMAC, timestamp, duplicate, and delivery contract.\n\nResolve startup failures\n\nStartup failures precede the AIP error surface. Inspect the first process error\nand compare it with Cal.diy configuration (../reference/configuration.md).\nCommon causes include:\n• an invalid base URL or account ID;\n• a mixed or incomplete authentication mode;\n• a secret file that is unreadable or exceeds its configured bound;\n• an invalid webhook secret mapping;\n• a missing central event endpoint for enabled ingress;\n• a database or manifest-discovery failure; or\n• a registry identity mismatch.\n\nCorrect one owning boundary at a time. Re-run readiness and the gateway-routed\nprofile read after every change; do not combine credential, account, artifact,\nand registry changes into one diagnostic restart.\n\nVerify the resolution\n\nClose the incident only when:\n• the signed error or startup failure no longer occurs for the corrected path;\n• /ready, the lifecycle lease, and tenant discovery agree;\n• a gateway-routed profile read reaches the intended account;\n• the original mutation is terminal or remains explicitly paused as uncertain;\n• the exact accepted webhook event appears centrally when ingress was affected;\n• no credential, raw provider body, webhook secret, or personal data entered\n  logs or the incident record.\n\nEscalate with:\n• the source revision plus artifact and manifest digests;\n• the tenant-safe identity set and timestamps;\n• the signed error plus action and transaction state;\n• provider operation and request IDs;\n• remote status, retry hint, and uncertainty flag;\n• readiness fields and metric snapshots; and\n• webhook event IDs and redacted logs.\n\nRelated documentation\n• Errors and retry decisions (../../../reference/errors.md)\n• Cal.diy authentication and tenant\n  routing (../getting-started/authentication-and-tenant-routing.md)\n• Cal.diy configuration (../reference/configuration.md)\n• Recover the Cal.diy connector (../operations/health-observability-and-recovery.md)\n• Cal.diy webhook security and replay (../reference/webhook-security-and-replay.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "36507fa26d862af82dc3a35e23be98893662981c9701a2c07ec6aa62f4cd2cf9"
  }
}