Errors

{
  "statusCode": 400,
  "error": "Bad request",
  "message": "failed_validation",
  "errors": [
    { "message": "amount is required", "fieldName": "amount" },
    { "message": "sourceCurrencyIso3Code length must be 3 characters long", "fieldName": "sourceCurrencyIso3Code" }
  ]
}

{
  "errors": [
    { "message": "Authentication failed", "context": {} }
  ]
}

[
  {
    "errors": {
      "message": "Insufficient Balance"
    }
  }
]

{
  "message": "account failed",
  "data": {
    "account": { "accountId": "2c3d4e5f-…", "uniqueRequestId": "acct_20261010_0005", "status": "failed" }
  }
}

const TIMEOUT_MS = 65_000; // a little above the gateway's 60-second limit

export const Outcome = Object.freeze({
  SUCCESS: 'success', // 2xx: use the body
  REFUSED: 'refused', // 4xx except 401: not carried out (check the exceptions in the docs)
  CHECK_API_KEY: 'check_api_key', // 401: the API key was refused; nothing happened, don't retry until it's fixed
  UNKNOWN: 'unknown', // 5xx, timeout or no response: look it up before retrying
});

// The API key comes from your secrets manager. Never log it.
export async function callMultigate(url, { method = 'GET', apiKey = process.env.MG_API_KEY, body } = {}) {
  let status = null;
  let text = '';
  try {
    const response = await fetch(url, {
      method,
      headers: {
        'mp-api-key': apiKey,
        'Content-Type': 'application/json',
        'Accept-Language': 'en',
      },
      body: body === undefined ? undefined : JSON.stringify(body),
      signal: AbortSignal.timeout(TIMEOUT_MS),
    });
    status = response.status;
    text = await response.text();
  } catch (error) {
    // Timeout, DNS failure, reset connection or a body cut off midway:
    // the request may have reached Multigate.
    return { outcome: Outcome.UNKNOWN, status, body: null, errors: [{ message: error.message }] };
  }

  const parsed = parseJson(text);
  if (status >= 200 && status < 300) {
    return { outcome: Outcome.SUCCESS, status, body: parsed, errors: [] };
  }
  return { outcome: classify(status), status, body: parsed, errors: readApiErrors(status, parsed) };
}

function parseJson(text) {
  try {
    return JSON.parse(text);
  } catch {
    return null; // empty, or an HTML page from the gateway
  }
}

function classify(status) {
  if (status === 401) return Outcome.CHECK_API_KEY;
  if (status >= 400 && status < 500) return Outcome.REFUSED;
  return Outcome.UNKNOWN; // 5xx and anything unexpected
}

export function readApiErrors(status, body) {
  const fallback = `HTTP ${status}`;
  if (Array.isArray(body)) {
    // Business rule error: [{ "errors": { "message", "code" } }]
    return body.map((item) => ({ message: item?.errors?.message ?? fallback, code: item?.errors?.code }));
  }
  if (body && Array.isArray(body.errors)) {
    // Validation error, error list or server error: { "errors": [{ "message", "fieldName" }] }
    return body.errors.map((item) => ({ message: item?.message ?? fallback, field: item?.fieldName }));
  }
  if (body && typeof body.message === 'string') {
    // Operation failed: { "message", "data", "code" }
    return [{ message: body.message, code: body.code }];
  }
  return [{ message: fallback }];
}

import os

import requests

TIMEOUT_SECONDS = 65  # a little above the gateway's 60-second limit

SUCCESS = "success"              # 2xx: use the body
REFUSED = "refused"              # 4xx except 401: not carried out (check the exceptions in the docs)
CHECK_API_KEY = "check_api_key"  # 401: the API key was refused; nothing happened, don't retry until it's fixed
UNKNOWN = "unknown"              # 5xx, timeout or no response: look it up before retrying


def call_multigate(method, url, body=None, api_key=None):
    api_key = api_key or os.environ["MG_API_KEY"]  # from your secrets manager; never log it
    try:
        response = requests.request(
            method,
            url,
            json=body,
            timeout=TIMEOUT_SECONDS,
            headers={"mp-api-key": api_key, "Accept-Language": "en"},
        )
    except requests.RequestException as error:
        # Timeout, DNS failure, reset connection or a body cut off midway:
        # the request may have reached Multigate.
        return {"outcome": UNKNOWN, "status": None, "body": None, "errors": [{"message": str(error)}]}

    status = response.status_code
    try:
        parsed = response.json()
    except ValueError:
        parsed = None  # empty, or an HTML page from the gateway

    if 200 <= status < 300:
        return {"outcome": SUCCESS, "status": status, "body": parsed, "errors": []}
    return {"outcome": classify(status), "status": status, "body": parsed, "errors": read_api_errors(status, parsed)}


def classify(status):
    if status == 401:
        return CHECK_API_KEY
    if 400 <= status < 500:
        return REFUSED
    return UNKNOWN  # 5xx and anything unexpected


def read_api_errors(status, body):
    fallback = f"HTTP {status}"
    if isinstance(body, list):
        # Business rule error: [{"errors": {"message", "code"}}]
        details = [item.get("errors") or {} if isinstance(item, dict) else {} for item in body]
        return [{"message": d.get("message", fallback), "code": d.get("code")} for d in details]
    if isinstance(body, dict) and isinstance(body.get("errors"), list):
        # Validation error, error list or server error: {"errors": [{"message", "fieldName"}]}
        items = [item if isinstance(item, dict) else {} for item in body["errors"]]
        return [{"message": i.get("message", fallback), "field": i.get("fieldName")} for i in items]
    if isinstance(body, dict) and isinstance(body.get("message"), str):
        # Operation failed: {"message", "data", "code"}
        return [{"message": body["message"], "code": body.get("code")}]
    return [{"message": fallback}]