{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition","tabs","tab"]},"type":"markdown"},"seo":{"title":"Reefpay Docs","description":"Reefpay is the groundbreaking payment gateway that lets you integrate with the future of payments.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"tutorial-log-and-monitor-api-errors","__idx":0},"children":["Tutorial: Log and monitor API errors"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"why-logging-matters","__idx":1},"children":["Why logging matters"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Payment errors are inevitable — network blips, expired cards, processor downtime. What separates a resilient integration from a brittle one is how quickly you detect and respond. Structured logs give you:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Root-cause analysis"]}," — trace a failed payment through every hop using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["correlation_id"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Trend detection"]}," — spot rising decline rates before customers complain."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Compliance evidence"]}," — auditable records for PCI-DSS and dispute resolution."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-to-log","__idx":2},"children":["What to log"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"required-fields","__idx":3},"children":["Required fields"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Source"},"children":["Source"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Example"},"children":["Example"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timestamp"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Your system"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2026-03-02T14:23:01.000Z"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["correlation_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Response body"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["http_method"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Request"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["endpoint"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Request"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/transactions"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["http_status"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Response"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["response_status"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Response body"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["declined"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["response_code"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Response body"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["05"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["response_message"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Response body"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Transaction declined by the issuer."]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["elapsed_ms"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Your system"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["342"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"useful-additions","__idx":4},"children":["Useful additions"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Purpose"},"children":["Purpose"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["idempotency_key"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Correlate retries"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Link to gateway record"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["processor_code"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Processor-specific debugging"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customer_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Correlate with your user"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-not-to-log","__idx":5},"children":["What NOT to log"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"danger","name":"PCI compliance"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Never log full card numbers (PAN), CVV, bank account numbers, or API keys. Violations can result in PCI-DSS non-compliance and significant fines."]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Log this instead"},"children":["Log this instead"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Full PAN (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["4111111111111111"]},")"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Last four (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["****1111"]},")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["CVV (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["123"]},")"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Never log"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["API key"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["****last4"]}," or omit"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Bank account number"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Last four (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["****6789"]},")"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"structured-logging-implementation","__idx":6},"children":["Structured logging implementation"]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Python","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"import json, logging, time, os, requests\n\nlogger = logging.getLogger(\"paradise\")\nhandler = logging.StreamHandler()\nhandler.setFormatter(logging.Formatter(\"%(message)s\"))\nlogger.addHandler(handler)\nlogger.setLevel(logging.INFO)\n\nAPI_KEY = os.environ[\"PARADISE_API_KEY\"]\nBASE = os.environ.get(\"PARADISE_BASE_URL\", \"https://api.dev.paradisegateway.net\")\n\ndef logged_request(method: str, path: str, payload: dict | None = None) -> dict:\n    url = f\"{BASE}{path}\"\n    headers = {\"Content-Type\": \"application/json\", \"APIKEY\": API_KEY}\n\n    start = time.monotonic()\n    try:\n        resp = requests.request(method, url, headers=headers, json=payload, timeout=30)\n        body = resp.json()\n        elapsed = int((time.monotonic() - start) * 1000)\n\n        log_entry = {\n            \"timestamp\": time.strftime(\"%Y-%m-%dT%H:%M:%S.000Z\", time.gmtime()),\n            \"level\": \"error\" if resp.status_code >= 400 else \"info\",\n            \"http_method\": method,\n            \"endpoint\": path,\n            \"http_status\": resp.status_code,\n            \"response_status\": body.get(\"response_status\"),\n            \"response_code\": body.get(\"response_code\"),\n            \"correlation_id\": body.get(\"correlation_id\"),\n            \"transaction_id\": body.get(\"id\"),\n            \"elapsed_ms\": elapsed,\n        }\n\n        if resp.status_code >= 400 or body.get(\"response_status\") in (\"declined\", \"error\"):\n            log_entry[\"response_message\"] = body.get(\"response_message\")\n            logger.error(json.dumps(log_entry))\n        else:\n            logger.info(json.dumps(log_entry))\n\n        return body\n    except Exception as e:\n        elapsed = int((time.monotonic() - start) * 1000)\n        logger.error(json.dumps({\n            \"timestamp\": time.strftime(\"%Y-%m-%dT%H:%M:%S.000Z\", time.gmtime()),\n            \"level\": \"error\",\n            \"http_method\": method,\n            \"endpoint\": path,\n            \"error\": str(e),\n            \"elapsed_ms\": elapsed,\n        }))\n        raise\n","lang":"python"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"JavaScript","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"const API_KEY = process.env.PARADISE_API_KEY;\nconst BASE = process.env.PARADISE_BASE_URL || \"https://api.dev.paradisegateway.net\";\n\nasync function loggedRequest(method, path, payload = null) {\n  const url = `${BASE}${path}`;\n  const start = Date.now();\n\n  try {\n    const resp = await fetch(url, {\n      method,\n      headers: { \"Content-Type\": \"application/json\", \"APIKEY\": API_KEY },\n      body: payload ? JSON.stringify(payload) : undefined,\n    });\n    const body = await resp.json();\n    const elapsed = Date.now() - start;\n\n    const logEntry = {\n      timestamp: new Date().toISOString(),\n      level: resp.status >= 400 ? \"error\" : \"info\",\n      http_method: method,\n      endpoint: path,\n      http_status: resp.status,\n      response_status: body.response_status,\n      response_code: body.response_code,\n      correlation_id: body.correlation_id,\n      transaction_id: body.id,\n      elapsed_ms: elapsed,\n    };\n\n    if (resp.status >= 400 || [\"declined\", \"error\"].includes(body.response_status)) {\n      logEntry.response_message = body.response_message;\n      console.error(JSON.stringify(logEntry));\n    } else {\n      console.info(JSON.stringify(logEntry));\n    }\n\n    return body;\n  } catch (err) {\n    console.error(JSON.stringify({\n      timestamp: new Date().toISOString(),\n      level: \"error\",\n      http_method: method,\n      endpoint: path,\n      error: err.message,\n      elapsed_ms: Date.now() - start,\n    }));\n    throw err;\n  }\n}\n","lang":"javascript"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"example-log-output","__idx":7},"children":["Example log output"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"approved-transaction","__idx":8},"children":["Approved transaction"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"timestamp\": \"2026-03-02T14:23:01.000Z\",\n  \"level\": \"info\",\n  \"http_method\": \"POST\",\n  \"endpoint\": \"/v1/transactions\",\n  \"http_status\": 200,\n  \"response_status\": \"approved\",\n  \"response_code\": \"00\",\n  \"correlation_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n  \"transaction_id\": \"TRANSACTION-01KEW32V6YNV11T33XGDR7TGWC\",\n  \"elapsed_ms\": 342\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"declined-transaction","__idx":9},"children":["Declined transaction"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"timestamp\": \"2026-03-02T14:24:15.000Z\",\n  \"level\": \"error\",\n  \"http_method\": \"POST\",\n  \"endpoint\": \"/v1/transactions\",\n  \"http_status\": 200,\n  \"response_status\": \"declined\",\n  \"response_code\": \"51\",\n  \"correlation_id\": \"b2c3d4e5-f6a7-8901-bcde-f12345678901\",\n  \"transaction_id\": \"TRANSACTION-01KEW33R7ZOW22U44YHES8UHXD\",\n  \"elapsed_ms\": 287,\n  \"response_message\": \"Insufficient funds\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"monitoring-and-alerting","__idx":10},"children":["Monitoring and alerting"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once you have structured logs, feed them into a monitoring system to catch issues early."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"https://files.modern-mermaid.live/images/1776277712786-mermaid-diagram-1776277712922.png","alt":"image"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"recommended-alerts","__idx":11},"children":["Recommended alerts"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Alert"},"children":["Alert"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Condition"},"children":["Condition"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Severity"},"children":["Severity"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["High decline rate"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Decline rate > 15% over 15 minutes"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Warning"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Elevated 5xx errors"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Any ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["5xx"]}," response from the API"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Critical"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Slow responses"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["elapsed_ms"]}," > 5000 for 5+ requests in 10 minutes"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Warning"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Auth failures"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}," responses spike"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Critical"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Unknown processor code"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Processor code not in your mapping"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Info"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"key-metrics-to-track","__idx":12},"children":["Key metrics to track"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Metric"},"children":["Metric"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"How to compute"},"children":["How to compute"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Why it matters"},"children":["Why it matters"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Approval rate"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["approved / total_transactions"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Core business health"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Decline rate by code"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Group declines by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["response_code"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Identify specific card issues"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["API latency (p50, p95, p99)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["elapsed_ms"]}," percentiles"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Performance regression detection"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Error rate"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["5xx_responses / total_requests"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Gateway availability"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retry rate"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Requests with same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["idempotency_key"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Indicates instability"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"using-correlation_id-for-troubleshooting","__idx":13},"children":["Using correlation_id for troubleshooting"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every response includes a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["correlation_id"]},". This value traces the request through Paradise Gateway's internal systems and to the processor."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Log the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["correlation_id"]}," alongside your internal order ID."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["When investigating an issue, query your logs by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["correlation_id"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["When contacting Paradise Gateway support, provide the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["correlation_id"]}," — it lets the team trace the request end-to-end."]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"log.info(\n    \"Payment for order %s: correlation_id=%s, status=%s\",\n    order_id,\n    response[\"correlation_id\"],\n    response[\"response_status\"],\n)\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"best-practices","__idx":14},"children":["Best practices"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Use structured JSON logs"]}," — not free-text strings. JSON logs are searchable and parseable by aggregation tools."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["correlation_id"]}," on every log line"]}," — it is your primary tracing key."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Redact sensitive data before logging"]}," — mask PAN, CVV, and API keys."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Set log retention"]}," — keep payment logs for at least 12 months for dispute resolution."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Separate payment logs"]}," — use a dedicated logger/channel for payment-related events to reduce noise."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":15},"children":["Next steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/tutorials/error-handling/retry-with-exponential-backoff"},"children":["Retry with exponential backoff"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/tutorials/error-handling/processor-specific-errors"},"children":["Processor-specific errors"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/concepts/api-fundamentals/error-handling"},"children":["Error handling concepts"]}]}]}]},"headings":[{"value":"Tutorial: Log and monitor API errors","id":"tutorial-log-and-monitor-api-errors","depth":1},{"value":"Why logging matters","id":"why-logging-matters","depth":2},{"value":"What to log","id":"what-to-log","depth":2},{"value":"Required fields","id":"required-fields","depth":3},{"value":"Useful additions","id":"useful-additions","depth":3},{"value":"What NOT to log","id":"what-not-to-log","depth":3},{"value":"Structured logging implementation","id":"structured-logging-implementation","depth":2},{"value":"Example log output","id":"example-log-output","depth":2},{"value":"Approved transaction","id":"approved-transaction","depth":3},{"value":"Declined transaction","id":"declined-transaction","depth":3},{"value":"Monitoring and alerting","id":"monitoring-and-alerting","depth":2},{"value":"Recommended alerts","id":"recommended-alerts","depth":3},{"value":"Key metrics to track","id":"key-metrics-to-track","depth":3},{"value":"Using correlation_id for troubleshooting","id":"using-correlation_id-for-troubleshooting","depth":2},{"value":"Best practices","id":"best-practices","depth":2},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"title":"Tutorial: Log and monitor API errors","shortTitle":"Log & monitor errors","intro":"Set up structured logging and monitoring for Paradise Gateway API errors so you can detect issues in real time and troubleshoot efficiently.","type":"tutorial","seo":{"title":""}},"lastModified":"2026-06-05T02:46:44.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/tutorials/error-handling/log-monitor-api-errors","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}