# Troubleshooting Guide

> Read this guide in full before starting diagnosis.
> Tools are listed by priority — try earlier tools first, escalate to later ones if unresolved. Diagnosis Gate Contract applies throughout.
>
> Suggested flow: collect evidence → Error Code Lookup → run API doc `Troubleshooting` Self-check → apply Diagnosis Gate Contract → CLI diagnosis → Dashboard diagnosis. Diagnosis Gate Contract applies throughout. If any step resolves the issue, stop and output Diagnosis Ledger.

---

## Information to Collect

Collect error details from user input, console output, or `antom_debug.log`. Require the following fields before changing code:

- API gateway/domain
- API endpoint
- Environment (sandbox/production)
- Safe request header summary (`Client-Id`, `Request-Time`, `keyVersion`, `Content-Type`; never log private keys or full signatures)
- HTTP status
- UTC time and local machine time
- Request body and response body
- `resultCode` and `resultMessage`
- Unique `requestId`/`paymentRequestId`
- Async notification payload (if applicable)

Mask sensitive fields before sharing or outputting evidence, including card numbers, CVV, private keys, and full signatures.

If the integration code cannot generate/pass a unique ID or log these fields, fix that integration defect first.

---

## Diagnostic Tools

### 1. Error Code Lookup

Match `resultCode` and `resultMessage` against known error patterns and API documentation:

- **FAQ (Errors)**: [FAQ (Errors)](https://cdn.marmot-cloud.com/page/antom-integration-doc/troubleshoot/faq-errors.md) — known error patterns with specific fixes. If the error matches, follow the Action to fix.
- **API Troubleshooting Index**: [API Troubleshooting Index](https://cdn.marmot-cloud.com/page/antom-integration-doc/troubleshoot/api-troubleshooting-index.md) — maps API endpoints to documentation. Look up the API endpoint or API name, find the corresponding API doc, locate its Result/Error codes section, and match `resultCode`.

In API Result/Error code tables, the `Troubleshooting` column provides local Self-check guidance. Run that guidance before following the table's `Further action`. `Self-check` is the agent action; `Further action` keeps the API documentation meaning.

**Missing Troubleshooting Column Self-check Compatibility** — if the `Troubleshooting` column is missing, inspect fields named by `resultMessage`; if no field is named, run only generic checks for evidence completeness, unique ID, raw JSON parseability, endpoint/environment/header/auth sanity, serialization/type encoding against visible API notes, and obvious body-structure defects. Do not invent API-specific route tables. If these checks do not prove a local defect, follow the API doc's existing `Further action` and continue to other tools.

### 2. Antom CLI Diagnosis

Structured diagnosis returning the error root cause and suggested fix. Requires `paymentRequestId`, CLI installation, and login.

```bash
# Verify CLI status and merchant identity
antom whoami
```

If `antom whoami` fails, use the official [Antom CLI documentation](https://docs.antom.com/ac/ref/antom_cli.md) for installation and login, then retry. The returned merchant identity must match the merchant being diagnosed.

```bash
# Run diagnosis (merchant identity must match)
antom integration diagnose --request-id <paymentRequestId> --json
```

The `--json` output includes the error root cause and suggested fix. Apply it only when the CLI evidence proves a local code or configuration defect. If the fix changes merchant intent, contract-dependent capability, payment method, settlement currency, goods, subscription, or authorization behavior, present it as a merchant-confirmed repair or diagnostic contrast before changing code. If the CLI is unavailable, the merchant identity does not match, or the diagnosis is inconclusive, use Dashboard diagnosis instead.

### 3. Dashboard Diagnosis

- Search by `paymentRequestId` in [Request Log](https://dashboard.antom.com/global-payments/developers/requestLog)
- Paste request ID into Copilot on [Antom Dashboard](https://dashboard.antom.com/) for AI diagnosis
- If unresolved, contact Antom support with a masked log snippet

---

## Diagnosis Gate Contract

Apply these gates throughout diagnosis, regardless of which diagnostic tool is used.

### Context & Scope

**Domain/Environment Consistency** — check whether gateway/domain, path, environment, `Client-Id`, key pair, and merchant region belong to the same context. Sandbox online calls use `/ams/sandbox/api/<endpoint>` with sandbox credentials; production calls use `/ams/api/<endpoint>` with production credentials. For regional gateways, use the API overview domain mapping: US merchants use `https://open.antglobal-us.com`, North America non-US merchants use the North America gateway, and Asia merchants use the SEA gateway. If the wrong regional domain returns a generic error such as `UNKNOWN_EXCEPTION`, treat it as a domain/environment mismatch candidate and verify with the correct same-context domain before changing business body fields.

**Context Budget** — search only the relevant field, resultCode, payment method, or API section. For field checks, extract the smallest enclosing Markdown section for the field path and its parent object, then stop. Do not load full API documents or large payment-method docs unless strictly necessary.

### Field Analysis

**Field-Path Spec Check Gate** — when `resultMessage` is generic or the visible request body contains unfamiliar fields, build a compact list of request field paths and compare only those paths against the current API documentation. Read the endpoint's Result/Error codes, then the smallest relevant field-definition sections for the parent object and field path. Mark each checked path as documented, conditionally required, unsupported, type/format mismatch, or capability/config dependent. If a nested field is not documented in the current API spec, treat removing it only as a diagnostic contrast unless the merchant confirms that field is not part of the intended integration.

**Evidence Promotion Gate** — do not promote an observed optional/config field into a troubleshooting checkpoint merely because it appears in the request. Inspect or repair that field only if it is named by `resultMessage`, required by the API spec, included in the API doc `Troubleshooting` guidance, indicated by remote diagnostics, or proven by a discriminating same-context replay where baseline replay fails and the minimal field repair succeeds. Same-context means the merchant's original endpoint, environment, gateway/domain, `Client-Id`, key pair, merchant configuration, and region are unchanged. If replay uses a different test account, credentials, gateway/domain, key pair, or merchant configuration, classify success only as cross-context body-shape validation; never present it as the merchant's root cause or as a "change ID" repair.

**Replay Scope Gate** — use a new unique `paymentRequestId` to verify a proven local fix, or to run a merchant-approved same-context replay when no local defect is proven. A same-context replay that succeeds while the original business body remains unchanged is a small transient/duplicate/replay-state branch, not the default path. If replay succeeds without a proven request-body repair, stop guessing and classify the result by replay scope before changing business body fields. If only a cross-context replay succeeds, go back to the merchant's original context and check domain/environment, credentials/signature, contract, settlement currency, payment-method capability, and remote logs before changing business body fields.

### Repair Discipline

**Body-first Repair** — if a checked request body, integration code, or API doc proves a concrete local defect, fix it and retry with a new unique `paymentRequestId`. Treat the issue as resolved only when the retry returns `SUCCESS`.

**Candidate Repair** — for parameter/config/capability-suspected cases, run visible prechecks first. Try minimal candidate repairs and call the API to verify only when the candidate does not change merchant intent, or when the merchant has confirmed the intended change. If a candidate succeeds but the original evidence did not prove the root cause, classify it as an `empirically_validated_fix`, provide the before/after contrast and merchant repair suggestion, and do not present it as a proven root cause.

**Merchant Intent Boundary** — if a candidate changes merchant intent such as currency, payment method, settlement currency, goods, authorization, or contract-dependent capability, treat it only as `diagnostic_contrast_only`. Provide the before/after contrast, the successful retry result if present, and a merchant repair suggestion such as confirming the original capability/configuration or approving the changed request behavior. For example, if removing an unsupported nested field or switching a forced payment method returns `SUCCESS`, present that as an optional successful alternative that requires merchant confirmation, not as the root cause or final fix. After merchant approval, present it as a merchant-confirmed alternative. Ask for merchant confirmation before using it as the final fix.

**Config/Capability Precheck** — for contract, payment-method capability, region/currency support, merchant account, auth, key, or environment issues, first list the visible request/config checks the merchant agent can perform and where to check them, such as merchant code/SDK config, Antom Dashboard credentials/payment methods/Finance, contract/capability docs, or payment-method docs. Name the exact field/config item to inspect (for example: clientId, key, environment, gateway/domain, merchant region, payment method enablement, amount/currency/region limits, settlement currencies, subscription capability, authorization capability, or the exact field path shown by the Field-Path Spec Check Gate). If the agent lacks permission or the visible checks do not prove a local defect, follow the API doc's `Further action`, then use diagnosis CLI, Dashboard, or support with the collected evidence.

---

## Diagnosis Ledger

Every troubleshooting answer must include a compact ledger with these fields. When a `Troubleshooting` column names documentation links, record those targeted links in `docLinksUsed` even if you only used the local API fragment and did not load the full linked document.

```json
{
  "evidenceGate": "pass|fail",
  "apiDocResultCodesRead": true,
  "apiDocSelfCheck": "used|missing|not_applicable",
  "compatibilityPathUsed": false,
  "domainEnvironmentConsistencyChecked": true,
  "bodyFirstCheckPerformed": true,
  "fieldPathSpecCheckPerformed": true,
  "fieldPathsChecked": [],
  "fieldPromotionEvidence": "none|result_message|api_spec|self_check|remote_diagnostics|discriminating_replay",
  "replayContextMatched": false,
  "replayScope": "not_run|same_context|cross_context_body_shape_only",
  "crossContextReplayUsedAsRootCause": false,
  "localDefectFound": false,
  "localDefect": "",
  "repairAttempted": false,
  "newPaymentRequestIdUsed": false,
  "retryResultCode": null,
  "resolved": false,
  "evidenceLevel": "proven_root_cause|empirically_validated_fix|diagnostic_contrast_only|no_local_defect|not_applicable",
  "merchantIntentChanged": false,
  "merchantConfirmationRequired": false,
  "configCapabilityPrecheckPerformed": false,
  "escalated": false,
  "escalationTarget": "none|further_action|dashboard|diagnosis_cli|support|dashboard_or_cli_or_support",
  "beforeAfterContrastProvided": false,
  "merchantRepairSuggestionProvided": false,
  "avoidedSpeculativeMutation": true,
  "avoidedHardCodedRoute": true,
  "loadedFullLargeDoc": false,
  "docLinksUsed": []
}
```

---

## After Diagnosis

- **Code fix**: apply the Skill's Security Red Lines and Debug Logs format. If the product or integration mode is unclear, identify it from the API endpoint in the error details before modifying code.
- **Configuration fix**: guide the user to update configuration in code or Dashboard (e.g., settlement currency, webhook URL).
- **Verify**: re-test in sandbox after any fix.
- **Escalate**: contact Antom support with a masked log snippet if the issue is beyond code or configuration.