Error Codes

{
  "error": {
    "type": "validation_error | authentication_error | authorization_error | not_found | conflict | unprocessable_entity | rate_limit | internal_error | connector_error",
    "code": "CE_001",
    "message": "Human-readable description",
    "request_id": "req_9f2a1b",
    "status": 400,
    "details": {
      "field": "amount",
      "reason": "must be >= 1"
    }
  }
}

{
  "error": {
    "type": "validation_error",
    "code": "CE_AMOUNT_INVALID",
    "message": "amount must be a positive integer",
    "request_id": "req_01H9K6N9ZQ7D2",
    "status": 400,
    "details": { "field": "amount" }
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "CE_AUTH_MISSING",
    "message": "Missing or invalid api-key",
    "request_id": "req_01H9K6QE8Z5D4",
    "status": 401
  }
}

{
  "error": {
    "type": "authorization_error",
    "code": "CE_FORBIDDEN",
    "message": "Not allowed for this key/profile",
    "request_id": "req_01H9K6XCM3V9S",
    "status": 403
  }
}

{
  "error": {
    "type": "not_found",
    "code": "CE_RESOURCE_MISSING",
    "message": "payment not found",
    "request_id": "req_01H9K70Q8E9C0",
    "status": 404
  }
}

{
  "error": {
    "type": "conflict",
    "code": "CE_STATE_CONFLICT",
    "message": "payment already captured",
    "request_id": "req_01H9K72Z4B1A7",
    "status": 409
  }
}

{
  "error": {
    "type": "unprocessable_entity",
    "code": "CE_RULE_VIOLATION",
    "message": "profile routing rule blocked this operation",
    "request_id": "req_01H9K75S5E3QF",
    "status": 422
  }
}

{
  "error": {
    "type": "rate_limit",
    "code": "CE_RL_429",
    "message": "Too many requests",
    "request_id": "req_01H9K78W6P9M2",
    "status": 429
  }
}

{
  "error": {
    "type": "connector_error",
    "code": "CE_CONNECTOR_TIMEOUT",
    "message": "Upstream connector timed out",
    "request_id": "req_01H9K7B8S4GJ9",
    "status": 504
  }
}

async function call(path, opts = {}) {
  const base = process.env.PAYMNT_BASE_URL || "https://sandbox.paymnt.cloud";
  const res = await fetch(`${base}${path}`, {
    ...opts,
    headers: {
      "Accept": "application/json",
      "api-key": process.env.PAYMNT_API_KEY,
      ...(opts.headers || {})
    }
  });

  const text = await res.text();
  const data = text ? JSON.parse(text) : null;

  if (!res.ok) {
    const err = data?.error || { status: res.status, message: "Unknown error" };
    // Log for observability
    console.error("Paymnt error", {
      status: err.status ?? res.status,
      code: err.code,
      type: err.type,
      request_id: err.request_id
    });
    throw new Error(`${err.type || "error"}: ${err.code || res.status} (${err.request_id || "no-request-id"})`);
  }

  return data;
}